@towns-protocol/contracts 0.0.302

package/src/base/registry/facets/operator/NodeOperatorFacet.sol

@@ -0,0 +1,189 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.23;
+
+// interfaces
+import {INodeOperator} from "./INodeOperator.sol";
+
+// libraries
+import {EnumerableSet} from "@openzeppelin/contracts/utils/structs/EnumerableSet.sol";
+import {NodeOperatorStatus, NodeOperatorStorage} from "src/base/registry/facets/operator/NodeOperatorStorage.sol";
+
+// contracts
+import {OwnableBase} from "@towns-protocol/diamond/src/facets/ownable/OwnableBase.sol";
+import {ERC721ABase} from "src/diamond/facets/token/ERC721A/ERC721ABase.sol";
+
+import {Facet} from "@towns-protocol/diamond/src/facets/Facet.sol";
+
+contract NodeOperatorFacet is INodeOperator, OwnableBase, ERC721ABase, Facet {
+    using EnumerableSet for EnumerableSet.AddressSet;
+
+    function __NodeOperator_init() external onlyInitializing {
+        _addInterface(type(INodeOperator).interfaceId);
+    }
+
+    // =============================================================
+    //                           Registration
+    // =============================================================
+
+    /// @inheritdoc INodeOperator
+    function registerOperator(address claimer) external {
+        if (claimer == address(0)) revert NodeOperator__InvalidAddress();
+
+        NodeOperatorStorage.Layout storage ds = NodeOperatorStorage.layout();
+
+        if (ds.operators.contains(msg.sender)) {
+            revert NodeOperator__AlreadyRegistered();
+        }
+
+        _mint(msg.sender, 1);
+
+        ds.operators.add(msg.sender);
+        ds.statusByOperator[msg.sender] = NodeOperatorStatus.Standby;
+        ds.claimerByOperator[msg.sender] = claimer;
+        ds.operatorsByClaimer[claimer].add(msg.sender);
+
+        emit OperatorRegistered(msg.sender);
+    }
+
+    // =============================================================
+    //                           Operator Status
+    // =============================================================
+
+    /// @inheritdoc INodeOperator
+    function isOperator(address operator) external view returns (bool) {
+        NodeOperatorStorage.Layout storage ds = NodeOperatorStorage.layout();
+        return ds.operators.contains(operator);
+    }
+
+    /// @inheritdoc INodeOperator
+    function setOperatorStatus(address operator, NodeOperatorStatus newStatus) external onlyOwner {
+        if (operator == address(0)) revert NodeOperator__InvalidAddress();
+
+        NodeOperatorStorage.Layout storage ds = NodeOperatorStorage.layout();
+
+        if (!ds.operators.contains(operator)) revert NodeOperator__NotRegistered();
+
+        NodeOperatorStatus currentStatus = ds.statusByOperator[operator];
+
+        if (currentStatus == newStatus) revert NodeOperator__StatusNotChanged();
+
+        // Check for valid newStatus transitions
+        // Exiting -> Standby
+        // Standby -> Approved
+        // Approved -> Exiting || Active
+        // Active -> Exiting || Approved
+        if (
+            currentStatus == NodeOperatorStatus.Exiting && newStatus != NodeOperatorStatus.Standby
+        ) {
+            revert NodeOperator__InvalidStatusTransition();
+        } else if (
+            currentStatus == NodeOperatorStatus.Standby && newStatus != NodeOperatorStatus.Approved
+        ) {
+            revert NodeOperator__InvalidStatusTransition();
+        } else if (
+            currentStatus == NodeOperatorStatus.Approved &&
+            (newStatus != NodeOperatorStatus.Exiting && newStatus != NodeOperatorStatus.Active)
+        ) {
+            revert NodeOperator__InvalidStatusTransition();
+        } else if (
+            currentStatus == NodeOperatorStatus.Active &&
+            (newStatus != NodeOperatorStatus.Exiting && newStatus != NodeOperatorStatus.Approved)
+        ) {
+            revert NodeOperator__InvalidStatusTransition();
+        }
+        if (newStatus == NodeOperatorStatus.Active) {
+            ds.approvalTimeByOperator[operator] = block.timestamp;
+        } else {
+            ds.approvalTimeByOperator[operator] = 0;
+        }
+        ds.statusByOperator[operator] = newStatus;
+
+        emit OperatorStatusChanged(operator, newStatus);
+    }
+
+    /// @inheritdoc INodeOperator
+    function getOperatorStatus(address operator) external view returns (NodeOperatorStatus) {
+        NodeOperatorStorage.Layout storage ds = NodeOperatorStorage.layout();
+        return ds.statusByOperator[operator];
+    }
+
+    // =============================================================
+    //                           Operator Info
+    // =============================================================
+
+    /// @inheritdoc INodeOperator
+    function setClaimAddressForOperator(
+        address claimer,
+        address operator
+    ) external onlyClaimer(msg.sender, operator) {
+        NodeOperatorStorage.Layout storage ds = NodeOperatorStorage.layout();
+
+        if (!ds.operators.contains(operator)) revert NodeOperator__NotRegistered();
+
+        address currentClaimer = ds.claimerByOperator[operator];
+
+        if (currentClaimer == claimer) {
+            revert NodeOperator__ClaimAddressNotChanged();
+        }
+
+        if (ds.operatorsByClaimer[currentClaimer].contains(operator)) {
+            ds.operatorsByClaimer[currentClaimer].remove(operator);
+        }
+
+        ds.claimerByOperator[operator] = claimer;
+        ds.operatorsByClaimer[claimer].add(operator);
+
+        emit OperatorClaimAddressChanged(operator, claimer);
+    }
+
+    /// @inheritdoc INodeOperator
+    function getClaimAddressForOperator(address operator) external view returns (address) {
+        return NodeOperatorStorage.layout().claimerByOperator[operator];
+    }
+
+    function getOperators() external view returns (address[] memory) {
+        NodeOperatorStorage.Layout storage ds = NodeOperatorStorage.layout();
+        return ds.operators.values();
+    }
+
+    // =============================================================
+    //                           Commission
+    // =============================================================
+    function setCommissionRate(uint256 rateBps) external {
+        NodeOperatorStorage.Layout storage ds = NodeOperatorStorage.layout();
+        if (!ds.operators.contains(msg.sender)) {
+            revert NodeOperator__NotRegistered();
+        }
+        if (rateBps > 10_000) revert NodeOperator__InvalidCommissionRate();
+
+        //only allow raising the commission if operator is in standby status
+        if (
+            rateBps > ds.commissionByOperator[msg.sender] &&
+            ds.statusByOperator[msg.sender] != NodeOperatorStatus.Standby
+        ) {
+            revert NodeOperator__InvalidCommissionRate();
+        }
+
+        ds.commissionByOperator[msg.sender] = rateBps;
+        emit OperatorCommissionChanged(msg.sender, rateBps);
+    }
+
+    function getCommissionRate(address operator) external view returns (uint256) {
+        NodeOperatorStorage.Layout storage ds = NodeOperatorStorage.layout();
+        return ds.commissionByOperator[operator];
+    }
+
+    // =============================================================
+    //                           Modifiers
+    // =============================================================
+
+    // only an existing claimer for that operator can call this function
+    modifier onlyClaimer(address claimer, address operator) {
+        NodeOperatorStorage.Layout storage ds = NodeOperatorStorage.layout();
+
+        if (!ds.operatorsByClaimer[claimer].contains(operator)) {
+            revert NodeOperator__NotClaimer();
+        }
+        _;
+    }
+}

package/src/base/registry/facets/operator/NodeOperatorStorage.sol

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.23;
+
+// interfaces
+
+// libraries
+import {EnumerableSet} from "@openzeppelin/contracts/utils/structs/EnumerableSet.sol";
+
+// contracts
+
+enum NodeOperatorStatus {
+    Exiting,
+    Standby,
+    Approved,
+    Active
+}
+
+library NodeOperatorStorage {
+    // keccak256(abi.encode(uint256(keccak256("factory.facets.operator.storage")) - 1)) &
+    // ~bytes32(uint256(0xff))
+    bytes32 internal constant STORAGE_SLOT =
+        0x988e8266be98e92aff755bdd688f8f4a2421e26daa6089c7e2668053a3bf5500;
+
+    struct Layout {
+        EnumerableSet.AddressSet operators;
+        mapping(address => NodeOperatorStatus) statusByOperator;
+        mapping(address => uint256) commissionByOperator;
+        mapping(address => address) claimerByOperator;
+        mapping(address => EnumerableSet.AddressSet) operatorsByClaimer;
+        mapping(address operator => uint256 approvalTime) approvalTimeByOperator;
+    }
+
+    function layout() internal pure returns (Layout storage l) {
+        bytes32 slot = STORAGE_SLOT;
+        assembly {
+            l.slot := slot
+        }
+    }
+}

package/src/base/registry/facets/xchain/IXChain.sol

@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.23;
+
+// interfaces
+
+import {IEntitlementCheckerBase} from "src/base/registry/facets/checker/IEntitlementChecker.sol";
+import {IEntitlementGatedBase} from "src/spaces/facets/gated/IEntitlementGated.sol";
+
+// libraries
+
+// contracts
+
+/// @dev Struct to hold voting context and avoid stack too deep
+struct VotingContext {
+    bytes32 transactionId;
+    address caller;
+    uint256 value;
+    bool completed;
+}
+
+/// @dev Struct to hold vote counting results
+struct VoteResults {
+    uint256 passed;
+    uint256 failed;
+    uint256 totalNodes;
+    IEntitlementGatedBase.NodeVoteStatus finalStatus;
+}
+
+interface IXChain is IEntitlementGatedBase, IEntitlementCheckerBase {
+    /// @notice Checks if a specific entitlement check request has been completed
+    /// @param transactionId The unique identifier of the transaction
+    /// @param requestId The ID of the specific check request
+    /// @return bool True if the check is completed, false otherwise
+    function isCheckCompleted(
+        bytes32 transactionId,
+        uint256 requestId
+    ) external view returns (bool);
+
+    /// @notice Allows protocol to provide a refund for a timed-out entitlement check
+    /// @dev Will revert if the contract has insufficient funds
+    /// @param senderAddress The address to receive the refund
+    /// @param transactionId The unique identifier of the transaction being checked
+    function provideXChainRefund(address senderAddress, bytes32 transactionId) external;
+
+    /// @notice Posts the result of an entitlement check from a node
+    /// @param transactionId The unique identifier of the transaction being checked
+    /// @param roleId The ID of the role being checked
+    /// @param result The vote result from the node (PASSED, FAILED, or NOT_VOTED)
+    function postEntitlementCheckResult(
+        bytes32 transactionId,
+        uint256 roleId,
+        NodeVoteStatus result
+    ) external;
+}

package/src/base/registry/facets/xchain/XChain.sol

@@ -0,0 +1,158 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.23;
+
+// interfaces
+import {IXChain, VotingContext, VoteResults} from "./IXChain.sol";
+import {IEntitlementGated} from "src/spaces/facets/gated/IEntitlementGated.sol";
+
+// libraries
+import {XChainLib} from "./XChainLib.sol";
+import {EnumerableSet} from "@openzeppelin/contracts/utils/structs/EnumerableSet.sol";
+import {CurrencyTransfer} from "src/utils/libraries/CurrencyTransfer.sol";
+import {CustomRevert} from "src/utils/libraries/CustomRevert.sol";
+import {XChainCheckLib} from "./XChainCheckLib.sol";
+
+// contracts
+import {Facet} from "@towns-protocol/diamond/src/facets/Facet.sol";
+import {EntitlementGated} from "src/spaces/facets/gated/EntitlementGated.sol";
+import {ReentrancyGuard} from "solady/utils/ReentrancyGuard.sol";
+import {OwnableBase} from "@towns-protocol/diamond/src/facets/ownable/OwnableBase.sol";
+
+contract XChain is IXChain, ReentrancyGuard, OwnableBase, Facet {
+    using EnumerableSet for EnumerableSet.AddressSet;
+    using EnumerableSet for EnumerableSet.UintSet;
+    using EnumerableSet for EnumerableSet.Bytes32Set;
+    using CustomRevert for bytes4;
+    using XChainCheckLib for XChainLib.Check;
+
+    function __XChain_init() external onlyInitializing {
+        _addInterface(type(IEntitlementGated).interfaceId);
+    }
+
+    /// @inheritdoc IXChain
+    function isCheckCompleted(
+        bytes32 transactionId,
+        uint256 requestId
+    ) external view returns (bool) {
+        return XChainLib.layout().checks[transactionId].voteCompleted[requestId];
+    }
+
+    /// @inheritdoc IXChain
+    function provideXChainRefund(address senderAddress, bytes32 transactionId) external onlyOwner {
+        if (!XChainLib.layout().requestsBySender[senderAddress].remove(transactionId)) {
+            EntitlementGated_TransactionCheckAlreadyCompleted.selector.revertWith();
+        }
+
+        XChainLib.Request storage request = XChainLib.layout().requests[transactionId];
+
+        if (request.completed) {
+            EntitlementGated_TransactionCheckAlreadyCompleted.selector.revertWith();
+        }
+
+        if (request.value == 0) {
+            EntitlementGated_InvalidValue.selector.revertWith();
+        }
+
+        request.completed = true;
+
+        XChainLib.Check storage check = XChainLib.layout().checks[transactionId];
+
+        // clean up checks if any
+        uint256 requestIdsLength = check.requestIds.length();
+        if (requestIdsLength > 0) {
+            for (uint256 i; i < requestIdsLength; ++i) {
+                uint256 requestId = check.requestIds.at(i);
+                check.voteCompleted[requestId] = true;
+            }
+        }
+
+        CurrencyTransfer.transferCurrency(
+            CurrencyTransfer.NATIVE_TOKEN,
+            address(this),
+            senderAddress,
+            request.value
+        );
+    }
+
+    /// @inheritdoc IXChain
+    function postEntitlementCheckResult(
+        bytes32 transactionId,
+        uint256 requestId,
+        NodeVoteStatus result
+    ) external nonReentrant {
+        XChainLib.Request storage request = XChainLib.layout().requests[transactionId];
+        XChainLib.Check storage check = XChainLib.layout().checks[transactionId];
+
+        VotingContext memory context = check.validateVotingEligibility(
+            request,
+            transactionId,
+            requestId
+        );
+
+        check.processNodeVote(requestId, result);
+        VoteResults memory voteResults = check.calculateVoteResults(requestId);
+
+        if (_hasReachedQuorum(voteResults)) {
+            _completeVotingForRequest(context, requestId, voteResults.finalStatus);
+        }
+    }
+
+    /// @notice Checks if quorum has been reached (more than half voted the same way)
+    /// @param results The vote counting results
+    /// @return hasQuorum True if quorum is reached
+    function _hasReachedQuorum(VoteResults memory results) internal pure returns (bool hasQuorum) {
+        uint256 quorumThreshold = results.totalNodes / 2;
+        return results.passed > quorumThreshold || results.failed > quorumThreshold;
+    }
+
+    /// @notice Completes the voting for a specific request and finalizes the transaction
+    /// @param context The voting context
+    /// @param requestId The request identifier
+    /// @param finalStatus The final voting status for this request
+    function _completeVotingForRequest(
+        VotingContext memory context,
+        uint256 requestId,
+        NodeVoteStatus finalStatus
+    ) internal {
+        // Mark this specific request as completed
+        XChainLib.layout().checks[context.transactionId].voteCompleted[requestId] = true;
+
+        // In V2, each entitlement check is independent - finalize immediately when voting completes
+        _finalizeTransaction(context, finalStatus);
+    }
+
+    /// @notice Finalizes the transaction and calls back to the original caller
+    /// @param context The voting context
+    /// @param finalStatus The final status to report
+    function _finalizeTransaction(
+        VotingContext memory context,
+        NodeVoteStatus finalStatus
+    ) internal {
+        // Mark transaction as completed and clean up
+        XChainLib.layout().requests[context.transactionId].completed = true;
+        XChainLib.layout().requestsBySender[context.caller].remove(context.transactionId);
+
+        // Call back to the original caller with the result
+        EntitlementGated(context.caller).postEntitlementCheckResultV2{value: context.value}(
+            context.transactionId,
+            0,
+            finalStatus
+        );
+    }
+
+    /*´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:*/
+    /*                           Internal                         */
+    /*.•°:°.´+˚.*°.˚:*.´•*.+°.•°:´*.´•*.•°.•°:°.´:•˚°.*°.˚:*.´+°.•*/
+
+    function _checkAllRequestsCompleted(bytes32 transactionId) internal view returns (bool) {
+        XChainLib.Check storage check = XChainLib.layout().checks[transactionId];
+
+        uint256 requestIdsLength = check.requestIds.length();
+        for (uint256 i; i < requestIdsLength; ++i) {
+            if (!check.voteCompleted[check.requestIds.at(i)]) {
+                return false;
+            }
+        }
+        return true;
+    }
+}

package/src/base/registry/facets/xchain/XChainCheckLib.sol

@@ -0,0 +1,105 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.23;
+
+// interfaces
+
+// libraries
+
+// contracts
+import {XChainLib} from "./XChainLib.sol";
+import {IEntitlementGatedBase} from "src/spaces/facets/gated/IEntitlementGated.sol";
+import {CustomRevert} from "src/utils/libraries/CustomRevert.sol";
+import {EnumerableSet} from "@openzeppelin/contracts/utils/structs/EnumerableSet.sol";
+import {VoteResults, VotingContext} from "./IXChain.sol";
+
+library XChainCheckLib {
+    using CustomRevert for bytes4;
+    using EnumerableSet for EnumerableSet.AddressSet;
+    using EnumerableSet for EnumerableSet.UintSet;
+
+    function validateVotingEligibility(
+        XChainLib.Check storage self,
+        XChainLib.Request storage request,
+        bytes32 transactionId,
+        uint256 requestId
+    ) internal view returns (VotingContext memory context) {
+        if (request.completed) {
+            IEntitlementGatedBase
+                .EntitlementGated_TransactionCheckAlreadyCompleted
+                .selector
+                .revertWith();
+        }
+
+        if (!self.requestIds.contains(requestId)) {
+            IEntitlementGatedBase.EntitlementGated_RequestIdNotFound.selector.revertWith();
+        }
+
+        if (!self.nodes[requestId].contains(msg.sender)) {
+            IEntitlementGatedBase.EntitlementGated_NodeNotFound.selector.revertWith();
+        }
+
+        if (self.voteCompleted[requestId]) {
+            IEntitlementGatedBase
+                .EntitlementGated_TransactionCheckAlreadyCompleted
+                .selector
+                .revertWith();
+        }
+
+        // Populate context with needed data
+        context.transactionId = transactionId;
+        context.caller = request.caller;
+        context.value = request.value;
+        context.completed = request.completed;
+    }
+
+    function processNodeVote(
+        XChainLib.Check storage self,
+        uint256 requestId,
+        IEntitlementGatedBase.NodeVoteStatus result
+    ) internal {
+        uint256 nodeCount = self.nodes[requestId].length();
+        bool voteRecorded = false;
+
+        for (uint256 i; i < nodeCount; ++i) {
+            IEntitlementGatedBase.NodeVote storage currentVote = self.votes[requestId][i];
+
+            if (currentVote.node == msg.sender) {
+                if (currentVote.vote != IEntitlementGatedBase.NodeVoteStatus.NOT_VOTED) {
+                    IEntitlementGatedBase.EntitlementGated_NodeAlreadyVoted.selector.revertWith();
+                }
+                currentVote.vote = result;
+                voteRecorded = true;
+                break; // Exit early once vote is recorded
+            }
+        }
+
+        if (!voteRecorded) {
+            IEntitlementGatedBase.EntitlementGated_NodeNotFound.selector.revertWith();
+        }
+    }
+
+    function calculateVoteResults(
+        XChainLib.Check storage self,
+        uint256 requestId
+    ) internal view returns (VoteResults memory results) {
+        results.totalNodes = self.nodes[requestId].length();
+
+        for (uint256 i; i < results.totalNodes; ++i) {
+            IEntitlementGatedBase.NodeVote storage vote = self.votes[requestId][i];
+
+            if (vote.vote == IEntitlementGatedBase.NodeVoteStatus.PASSED) {
+                unchecked {
+                    ++results.passed;
+                }
+            } else if (vote.vote == IEntitlementGatedBase.NodeVoteStatus.FAILED) {
+                unchecked {
+                    ++results.failed;
+                }
+            }
+        }
+
+        results.finalStatus = results.passed > results.failed
+            ? IEntitlementGatedBase.NodeVoteStatus.PASSED
+            : IEntitlementGatedBase.NodeVoteStatus.FAILED;
+    }
+}

package/src/base/registry/facets/xchain/XChainLib.sol

@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.23;
+
+// interfaces
+import {IEntitlementChecker} from "src/base/registry/facets/checker/IEntitlementChecker.sol";
+import {IEntitlementGatedBase} from "src/spaces/facets/gated/IEntitlementGated.sol";
+// libraries
+import {EnumerableSet} from "@openzeppelin/contracts/utils/structs/EnumerableSet.sol";
+
+// contracts
+
+library XChainLib {
+    // keccak256(abi.encode(uint256(keccak256("xchain.entitlement.transactions.storage")) - 1)) &
+    // ~bytes32(uint256(0xff))
+    bytes32 internal constant STORAGE_SLOT =
+        0xf501c51c066c21fd640901535874a71171bb35113f6dc2832fce1b1f9da0cc00;
+
+    struct Check {
+        EnumerableSet.UintSet requestIds;
+        mapping(uint256 requestId => EnumerableSet.AddressSet) nodes;
+        mapping(uint256 requestId => IEntitlementGatedBase.NodeVote[]) votes;
+        mapping(uint256 requestId => bool voteCompleted) voteCompleted;
+    }
+
+    struct Request {
+        uint256 value;
+        uint256 blockNumber;
+        address caller;
+        bool completed;
+        address receiver;
+    }
+
+    struct Layout {
+        IEntitlementChecker entitlementChecker;
+        mapping(address => EnumerableSet.Bytes32Set) requestsBySender;
+        mapping(bytes32 => Request) requests;
+        mapping(bytes32 => Check) checks;
+    }
+
+    function layout() internal pure returns (Layout storage l) {
+        bytes32 slot = STORAGE_SLOT;
+        assembly {
+            l.slot := slot
+        }
+    }
+}

package/src/diamond/facets/beacon/UpgradeableBeacon.sol

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.23;
+
+abstract contract UpgradeableBeaconBase {
+    /// @dev The new implementation is not a deployed contract.
+    error NewImplementationHasNoCode();
+
+    /// @dev Emitted when the proxy's implementation is upgraded.
+    event Upgraded(address indexed implementation);
+
+    /// @dev `keccak256(bytes("Upgraded(address)"))`.
+    uint256 private constant _UPGRADED_EVENT_SIGNATURE =
+        0xbc7cd75a20ee27fd9adebab32041f755214dbc6bffa90cc0225b39da2e5c2d3b;
+
+    /// @dev The storage slot for the implementation address.
+    /// `uint72(bytes9(keccak256("_UPGRADEABLE_BEACON_IMPLEMENTATION_SLOT")))`.
+    uint256 internal constant _UPGRADEABLE_BEACON_IMPLEMENTATION_SLOT = 0x911c5a209f08d5ec5e;
+
+    function __UpgradeableBeacon_init_unchained(address initialImplementation) internal {
+        _setImplementation(initialImplementation);
+    }
+
+    /// @dev Sets the implementation directly without authorization guard.
+    function _setImplementation(address newImplementation) internal virtual {
+        /// @solidity memory-safe-assembly
+        assembly {
+            newImplementation := shr(96, shl(96, newImplementation)) // Clean the upper 96 bits.
+            if iszero(extcodesize(newImplementation)) {
+                mstore(0x00, 0x6d3e283b) // `NewImplementationHasNoCode()`.
+                revert(0x1c, 0x04)
+            }
+            sstore(_UPGRADEABLE_BEACON_IMPLEMENTATION_SLOT, newImplementation) // Store the
+            // implementation.
+            // Emit the {Upgraded} event.
+            log2(codesize(), 0x00, _UPGRADED_EVENT_SIGNATURE, newImplementation)
+        }
+    }
+}

package/src/diamond/facets/beacon/UpgradeableBeaconFacet.sol

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.23;
+
+// interfaces
+
+// libraries
+
+// contracts
+import {UpgradeableBeaconBase} from "src/diamond/facets/beacon/UpgradeableBeacon.sol";
+import {OwnableBase} from "@towns-protocol/diamond/src/facets/ownable/OwnableBase.sol";
+import {Facet} from "@towns-protocol/diamond/src/facets/Facet.sol";
+
+/// @notice Upgradeable beacon for ERC1967 beacon proxies.
+/// @author Modified from Solady
+/// (https://github.com/vectorized/solady/blob/main/src/utils/UpgradeableBeacon.sol)
+contract UpgradeableBeaconFacet is UpgradeableBeaconBase, OwnableBase, Facet {
+    function __UpgradeableBeacon_init(address initialImplementation) external onlyInitializing {
+        __UpgradeableBeacon_init_unchained(initialImplementation);
+    }
+
+    /// @dev Allows the owner to upgrade the implementation.
+    function upgradeTo(address newImplementation) public virtual onlyOwner {
+        _setImplementation(newImplementation);
+    }
+
+    /// @dev Returns the implementation stored in the beacon.
+    /// See: https://eips.ethereum.org/EIPS/eip-1967#beacon-contract-address
+    function implementation() public view returns (address result) {
+        /// @solidity memory-safe-assembly
+        assembly {
+            result := sload(_UPGRADEABLE_BEACON_IMPLEMENTATION_SLOT)
+        }
+    }
+}