@piplabs/story-contracts 0.1.0-alpha.0

package/script/utils/EIP1967Helper.sol

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: MIT
+/* solhint-disable max-line-length */
+pragma solidity 0.8.23;
+
+import { Vm } from "forge-std/Vm.sol";
+
+/// @title EIP1967Helper
+/// @dev Testing library to help with reading EIP 1967 variables from state
+/// @custom:attribution https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/test/mocks/EIP1967Helper.sol
+library EIP1967Helper {
+    /// @notice The storage slot that holds the address of a proxy implementation.
+    /// @dev `bytes32(uint256(keccak256('eip1967.proxy.implementation')) - 1)`
+    bytes32 internal constant PROXY_IMPLEMENTATION_SLOT =
+        0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc;
+
+    /// @notice The storage slot that holds the address of the owner.
+    /// @dev `bytes32(uint256(keccak256('eip1967.proxy.admin')) - 1)`
+    bytes32 internal constant PROXY_ADMIN_SLOT = 0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103;
+
+    Vm internal constant vm = Vm(0x7109709ECfa91a80626fF3989D68f67F5b1DD12D);
+
+    function getAdmin(address _proxy) internal view returns (address) {
+        return address(uint160(uint256(vm.load(address(_proxy), PROXY_ADMIN_SLOT))));
+    }
+
+    function setAdmin(address _addr, address _admin) internal {
+        vm.store(_addr, PROXY_ADMIN_SLOT, bytes32(uint256(uint160(_admin))));
+    }
+
+    function getImplementation(address _proxy) internal view returns (address) {
+        return address(uint160(uint256(vm.load(address(_proxy), PROXY_IMPLEMENTATION_SLOT))));
+    }
+
+    function setImplementation(address _addr, address _impl) internal {
+        vm.store(_addr, PROXY_IMPLEMENTATION_SLOT, bytes32(uint256(uint160(_impl))));
+    }
+}

package/script/utils/InitializableHelper.sol

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity 0.8.23;
+
+import { Vm } from "forge-std/Vm.sol";
+
+/**
+ * @title InitializableHelper
+ * @notice Helper library to read / manipulate OpenZeppelin v5 Initializable storage
+ */
+library InitializableHelper {
+    Vm internal constant vm = Vm(0x7109709ECfa91a80626fF3989D68f67F5b1DD12D);
+
+    // keccak256(abi.encode(uint256(keccak256("openzeppelin.storage.Initializable")) - 1)) & ~bytes32(uint256(0xff))
+    bytes32 private constant INITIALIZABLE_STORAGE = 0xf0c57e16840df040f15088dc2f81fe391c3923bec73e23a9662efc9c229c6a00;
+
+    // INITIALIZABLE_STORAGE stores the following struct:
+    //
+    // struct InitializableStorage {
+    //     /**
+    //      * @dev Indicates that the contract has been initialized.
+    //      */
+    //     uint64 _initialized;
+    //     /**
+    //      * @dev Indicates that the contract is in the process of being initialized.
+    //      */
+    //     bool _initializing;
+    // }
+
+    /**
+     * @notice Returns the Initializable._initialized value for a given address, at slot 0.
+     * @dev Reverts in _initializing.
+     */
+    function getInitialized(address addr) internal view returns (uint64) {
+        // _initialized is the first field in the storage layout
+        bytes32 slot = vm.load(addr, INITIALIZABLE_STORAGE);
+
+        // if _initializing is false, it's bit will be 0, and will not affect uint conversion
+        // if _initializing is true, it's bit will be 1, and will affect uint conversion
+        // we therefore require it is 0
+        require(uint256(slot) <= uint256(type(uint64).max), "initializing");
+
+        return uint64(uint256(slot));
+    }
+
+    /**
+     * @notice Returns true if the address has been initialized.
+     */
+    function isInitialized(address addr) internal view returns (bool) {
+        return getInitialized(addr) == uint64(1);
+    }
+
+    /**
+     * @notice Returns true if the initializers are disabled for a given address.
+     */
+    function areInitializersDisabled(address addr) internal view returns (bool) {
+        return getInitialized(addr) == type(uint64).max;
+    }
+
+    /**
+     * @notice Disables the initializers for a given address.
+     * @dev Sets _initialized to max uint64 (0xFFFFFFFFFFFFFFFF), which disables all initializers.
+     */
+    function disableInitializers(address addr) internal {
+        vm.store(addr, INITIALIZABLE_STORAGE, bytes32(uint256(type(uint64).max)));
+    }
+}

package/src/deploy/Create3.sol

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: AGPL-3.0
+pragma solidity 0.8.23;
+
+import { CREATE3 } from "solmate/src/utils/CREATE3.sol";
+
+/**
+ * @title Create3
+ * @notice Factory for deploying contracts to deterministic addresses via CREATE3 Enables deploying
+ *         contracts using CREATE3.
+ *         It is based on Zefram’s implementation and includes support for deployment using only a salt value.
+ *         It support two deployment styles:
+ *         1. Each deployer (msg.sender) has its own namespace for deployed addresses.
+ *         2. Deterministic deployment using a single salt.
+ * @custom:attribution zefram.eth (https://github.com/ZeframLou/create3-factory/blob/main/src/CREATE3Factory.sol)
+ */
+contract Create3 {
+    /**
+     * @notice Deploys a contract using CREATE3
+     * @dev The provided salt is hashed together with msg.sender to generate the final salt
+     * @param salt          The deployer-specific salt for determining the deployed contract's address
+     * @param creationCode  The creation code of the contract to deploy
+     * @return deployed     The address of the deployed contract
+     */
+    function deploy(bytes32 salt, bytes memory creationCode) external payable returns (address deployed) {
+        // hash salt with the deployer address to give each deployer its own namespace
+        salt = keccak256(abi.encodePacked(msg.sender, salt));
+        return CREATE3.deploy(salt, creationCode, msg.value);
+    }
+
+    /**
+     * @notice Predicts the address of a deployed contract
+     * @dev The provided salt is hashed together with the deployer address to generate the final salt
+     * @param deployer  The deployer account that will call deploy()
+     * @param salt      The deployer-specific salt for determining the deployed contract's address
+     * @return deployed The address of the contract that will be deployed
+     */
+    function getDeployed(address deployer, bytes32 salt) external view returns (address deployed) {
+        // hash salt with the deployer address to give each deployer its own namespace
+        salt = keccak256(abi.encodePacked(deployer, salt));
+        return CREATE3.getDeployed(salt);
+    }
+
+    /**
+     * @notice Deploys a contract using CREATE3
+     * @param salt          The deployer-specific salt for determining the deployed contract's address
+     * @param creationCode  The creation code of the contract to deploy
+     * @return deployed     The address of the deployed contract
+     */
+    function deployDeterministic(bytes memory creationCode, bytes32 salt) external payable returns (address deployed) {
+        return CREATE3.deploy(salt, creationCode, msg.value);
+    }
+
+    /**
+     * @notice Predicts the address of a deployed contract
+     * @param salt      The deployer-specific salt for determining the deployed contract's address
+     * @return deployed The address of the contract that will be deployed
+     */
+    function predictDeterministicAddress(bytes32 salt) external view returns (address deployed) {
+        // hash salt with the deployer address to give each deployer its own namespace
+        return CREATE3.getDeployed(salt);
+    }
+}

package/src/interfaces/IIPTokenStaking.sol

@@ -0,0 +1,303 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity 0.8.23;
+
+/// @title IIPTokenStaking
+/// @notice Interface for the IPTokenStaking contract
+interface IIPTokenStaking {
+    /// @notice Enum representing the different staking periods
+    /// @dev FLEXIBLE is used for flexible staking, where the staking period is not fixed and can be changed by the user
+    /// SHORT, MEDIUM, and LONG are used for staking with specific periods
+    enum StakingPeriod {
+        FLEXIBLE,
+        SHORT,
+        MEDIUM,
+        LONG
+    }
+
+    /// @notice Struct for initialize method args
+    /// @dev Contains various parameters for the contract's functionality
+    /// @param owner The address of the admin addres
+    /// @param minStakeAmount Global minimum amount required to stake
+    /// @param minUnstakeAmount Global minimum amount required to unstake
+    /// @param minCommissionRate Global minimum commission rate for validators
+    /// @param fee The fee charged for adding to CL storage
+    struct InitializerArgs {
+        address owner;
+        uint256 minStakeAmount;
+        uint256 minUnstakeAmount;
+        uint256 minCommissionRate;
+        uint256 fee;
+    }
+
+    /// @notice Emitted when the fee charged for adding to CL storage is updated
+    /// @param newFee The new fee
+    event FeeSet(uint256 newFee);
+
+    /// @notice Emitted when a new validator is created.
+    /// @param validatorCmpPubkey 33 bytes compressed secp256k1 public key.
+    /// @param moniker The moniker of the validator.
+    /// @param stakeAmount Token staked to the validator as self-delegation.
+    /// @param commissionRate The commission rate of the validator.
+    /// @param maxCommissionRate The maximum commission rate of the validator.
+    /// @param maxCommissionChangeRate The maximum commission change rate of the validator.
+    /// @param supportsUnlocked Whether the validator supports unlocked staking
+    /// @param operatorAddress The caller's address
+    /// @param data Additional data for the validator
+    event CreateValidator(
+        bytes validatorCmpPubkey,
+        string moniker,
+        uint256 stakeAmount,
+        uint32 commissionRate,
+        uint32 maxCommissionRate,
+        uint32 maxCommissionChangeRate,
+        uint8 supportsUnlocked,
+        address operatorAddress,
+        bytes data
+    );
+
+    /// @notice Emitted when the withdrawal address is set/changed.
+    /// @param delegator The delegator's address
+    /// @param executionAddress Left-padded 32 bytes of the EVM address to receive stake and reward withdrawals.
+    event SetWithdrawalAddress(address delegator, bytes32 executionAddress);
+
+    /// @notice Emitted when the rewards address is set/changed.
+    /// @param delegator The delegator's address
+    /// @param executionAddress Left-padded 32 bytes of the EVM address to receive stake and reward withdrawals.
+    event SetRewardAddress(address delegator, bytes32 executionAddress);
+
+    /// @notice Emitted when the validator commission is updated
+    /// @param validatorCmpPubkey 33 bytes compressed secp256k1 public key.
+    /// @param commissionRate The new commission rate of the validator.
+    event UpdateValidatorCommission(bytes validatorCmpPubkey, uint32 commissionRate);
+
+    /// @notice Emitted when a user deposits token into the contract.
+    /// @param delegator The delegator's address
+    /// @param validatorCmpPubkey 33 bytes compressed secp256k1 public key.
+    /// @param stakeAmount Token deposited
+    /// @param stakingPeriod The staking period of the deposit
+    /// @param delegationId The ID of the delegation
+    /// @param operatorAddress The caller's address
+    /// @param data Additional data for the deposit
+    event Deposit(
+        address delegator,
+        bytes validatorCmpPubkey,
+        uint256 stakeAmount,
+        uint256 stakingPeriod,
+        uint256 delegationId,
+        address operatorAddress,
+        bytes data
+    );
+
+    /// @notice Emitted when a user withdraws her stake and starts the unbonding period.
+    /// @param delegator The delegator's address
+    /// @param validatorCmpPubkey 33 bytes compressed secp256k1 public key.
+    /// @param stakeAmount Token unstaked. WARNING: This amount is rounded down to STAKE_ROUNDING.
+    /// @param delegationId The ID of the delegation, 0 if flexible
+    /// @param operatorAddress The caller's address
+    /// @param data Additional data for the deposit
+    event Withdraw(
+        address delegator,
+        bytes validatorCmpPubkey,
+        uint256 stakeAmount,
+        uint256 delegationId,
+        address operatorAddress,
+        bytes data
+    );
+
+    /// @notice Emitted when a user triggers redelegation of token from source validator to destination validator.
+    /// @param delegator The delegator's address
+    /// @param validatorSrcCmpPubkey 33 bytes compressed secp256k1 public key.
+    /// @param validatorDstCmpPubkey 33 bytes compressed secp256k1 public key.
+    /// @param delegationId if delegation has staking period, 0 if flexible
+    /// @param operatorAddress The caller's address
+    /// @param amount Token redelegated.
+    event Redelegate(
+        address delegator,
+        bytes validatorSrcCmpPubkey,
+        bytes validatorDstCmpPubkey,
+        uint256 delegationId,
+        address operatorAddress,
+        uint256 amount
+    );
+
+    /// @notice Emitted to request setting an operator address to a delegator
+    /// @param delegator The delegator's address
+    /// @param operator The operator's address
+    event SetOperator(address delegator, address operator);
+
+    /// @notice Emitted to request removing the operator address to a delegator
+    /// @param delegator The delegator's address
+    event UnsetOperator(address delegator);
+
+    /// @notice Emitted when the minimum stake amount is set.
+    /// @param minStakeAmount The new minimum stake amount.
+    event MinStakeAmountSet(uint256 minStakeAmount);
+
+    /// @notice Emitted when the minimum unstake amount is set.
+    /// @param minUnstakeAmount The new minimum unstake amount.
+    event MinUnstakeAmountSet(uint256 minUnstakeAmount);
+
+    /// @notice Emitted when the global minimum commission rate is set.
+    /// @param minCommissionRate The new global minimum commission rate.
+    event MinCommissionRateChanged(uint256 minCommissionRate);
+
+    /// @notice Emitted when a validator is unjailed.
+    /// @param unjailer The unjailer's address
+    /// @param validatorCmpPubkey 33 bytes compressed secp256k1 public key.
+    /// @param data Additional data for the unjail.
+    event Unjail(address unjailer, bytes validatorCmpPubkey, bytes data);
+
+    /// @notice Returns the rounded stake amount and the remainder.
+    /// @param rawAmount The raw stake amount.
+    /// @return amount The rounded stake amount.
+    /// @return remainder The remainder of the stake amount.
+    function roundedStakeAmount(uint256 rawAmount) external view returns (uint256 amount, uint256 remainder);
+
+    /// @notice Sets an operator for a delegator.
+    /// Calling this method will override any existing operator.
+    /// @param operator The operator address to add.
+    function setOperator(address operator) external payable;
+
+    /// @notice Removes current operator for a delegator.
+    function unsetOperator() external payable;
+
+    /// @notice Set/Update the withdrawal address that receives the withdrawals.
+    /// Charges fee (CL spam prevention). Must be exact amount.
+    /// @param newWithdrawalAddress EVM address to receive the  withdrawals.
+    function setWithdrawalAddress(address newWithdrawalAddress) external payable;
+
+    /// @notice Set/Update the withdrawal address that receives the stake and reward withdrawals.
+    /// Charges fee (CL spam prevention). Must be exact amount.
+    /// @param newRewardsAddress EVM address to receive the stake and reward withdrawals.
+    function setRewardsAddress(address newRewardsAddress) external payable;
+
+    /// @notice Update the commission rate of a validator.
+    /// Charges fee (CL spam prevention). Must be exact amount.
+    /// @param validatorCmpPubkey 33 bytes compressed secp256k1 public key.
+    /// @param commissionRate The new commission rate of the validator.
+    function updateValidatorCommission(bytes calldata validatorCmpPubkey, uint32 commissionRate) external payable;
+
+    /// @notice Entry point for creating a new validator with self delegation.
+    /// @dev The caller must provide the compressed public key that matches the expected EVM address.
+    /// Use this method to make sure the caller is the owner of the validator.
+    /// @param validatorCmpPubkey 33 bytes compressed secp256k1 public key.
+    /// @param moniker The moniker of the validator.
+    /// @param commissionRate The commission rate of the validator.
+    /// @param maxCommissionRate The maximum commission rate of the validator.
+    /// @param maxCommissionChangeRate The maximum commission change rate of the validator.
+    /// @param supportsUnlocked Whether the validator supports unlocked staking.
+    /// @param data Additional data for the validator.
+    function createValidator(
+        bytes calldata validatorCmpPubkey,
+        string calldata moniker,
+        uint32 commissionRate,
+        uint32 maxCommissionRate,
+        uint32 maxCommissionChangeRate,
+        bool supportsUnlocked,
+        bytes calldata data
+    ) external payable;
+
+    /// @notice Entry point to stake (delegate) to the given validator. The consensus client (CL) is notified of
+    /// the deposit and manages the stake accounting and validator onboarding. Payer must be the delegator.
+    /// @dev Staking burns tokens in Execution Layer (EL). Unstaking (withdrawal) will trigger minting through
+    /// withdrawal queue.
+    /// @param validatorCmpPubkey 33 bytes compressed secp256k1 public key.
+    /// @param stakingPeriod The staking period.
+    /// @param data Additional data for the stake.
+    /// @return delegationId The delegation ID, always 0 for flexible staking.
+    function stake(
+        bytes calldata validatorCmpPubkey,
+        StakingPeriod stakingPeriod,
+        bytes calldata data
+    ) external payable returns (uint256 delegationId);
+
+    /// @notice Entry point for staking IP token to stake to the given validator. The consensus chain is notified of
+    /// the stake and manages the stake accounting and validator onboarding. Payer can stake on behalf of another user,
+    /// who will be the beneficiary of the stake.
+    /// @dev Staking burns tokens in Execution Layer (EL). Unstaking (withdrawal) will trigger minting through
+    /// withdrawal queue.
+    /// @param delegator The delegator's address
+    /// @param validatorCmpPubkey 33 bytes compressed secp256k1 public key.
+    /// @param stakingPeriod The staking period.
+    /// @param data Additional data for the stake.
+    /// @return delegationId The delegation ID, always 0 for flexible staking.
+    function stakeOnBehalf(
+        address delegator,
+        bytes calldata validatorCmpPubkey,
+        StakingPeriod stakingPeriod,
+        bytes calldata data
+    ) external payable returns (uint256 delegationId);
+
+    /// @notice Entry point for redelegating the stake to another validator.
+    /// Charges fee (CL spam prevention). Must be exact amount.
+    /// @dev For non flexible staking, your staking period will continue as is.
+    /// @dev For locked tokens, this will fail in CL if the validator doesn't support unlocked staking.
+    /// @param validatorSrcCmpPubkey 33 bytes compressed secp256k1 public key.
+    /// @param validatorDstCmpPubkey 33 bytes compressed secp256k1 public key.
+    /// @param delegationId The delegation ID, 0 for flexible staking.
+    /// @param amount The amount of stake to redelegate.
+    function redelegate(
+        bytes calldata validatorSrcCmpPubkey,
+        bytes calldata validatorDstCmpPubkey,
+        uint256 delegationId,
+        uint256 amount
+    ) external payable;
+
+    /// @notice Entry point for redelegating the stake to another validator on behalf of the delegator.
+    /// Charges fee (CL spam prevention). Must be exact amount.
+    /// @dev For non flexible staking, your staking period will continue as is.
+    /// @dev For locked tokens, this will fail in CL if the validator doesn't support unlocked staking.
+    /// @dev Caller must be the operator for the delegator, set via `setOperator`. The operator check is done in CL, so
+    /// this method will succeed even if the caller is not the operator (but will fail in CL).
+    /// @param delegator The delegator's address
+    /// @param validatorSrcCmpPubkey 33 bytes compressed secp256k1 public key.
+    /// @param validatorDstCmpPubkey 33 bytes compressed secp256k1 public key.
+    /// @param delegationId The delegation ID, 0 for flexible staking.
+    /// @param amount The amount of stake to redelegate.
+    function redelegateOnBehalf(
+        address delegator,
+        bytes calldata validatorSrcCmpPubkey,
+        bytes calldata validatorDstCmpPubkey,
+        uint256 delegationId,
+        uint256 amount
+    ) external payable;
+
+    /// @notice Entry point for unstaking the previously staked token.
+    /// NOTE: If the amount is not divisible by STAKE_ROUNDING, it will be rounded down.
+    /// @dev Unstake (withdrawal) will trigger native minting, so token in this contract is considered as burned.
+    /// Charges fee (CL spam prevention). Must be exact amount.
+    /// @param validatorCmpPubkey 33 bytes compressed secp256k1 public key.
+    /// @param delegationId The delegation ID, 0 for flexible staking.
+    /// @param amount Token amount to unstake. This amount will be rounded down to STAKE_ROUNDING.
+    /// @param data Additional data for the unstake.
+    function unstake(
+        bytes calldata validatorCmpPubkey,
+        uint256 delegationId,
+        uint256 amount,
+        bytes calldata data
+    ) external payable;
+
+    /// @notice Entry point for unstaking the previously staked token on behalf of the delegator.
+    /// Charges fee (CL spam prevention). Must be exact amount.
+    /// NOTE: If the amount is not divisible by STAKE_ROUNDING, it will be rounded down.
+    /// @dev Caller must be the operator for the delegator, set via `setOperator`. The operator check is done in CL, so
+    /// this method will succeed even if the caller is not the operator (but will fail in CL).
+    /// @param delegator The delegator's address
+    /// @param validatorCmpPubkey 33 bytes compressed secp256k1 public key.
+    /// @param delegationId The delegation ID, 0 for flexible staking.
+    /// @param amount Token amount to unstake. This amount will be rounded down to STAKE_ROUNDING.
+    /// @param data Additional data for the unstake.
+    function unstakeOnBehalf(
+        address delegator,
+        bytes calldata validatorCmpPubkey,
+        uint256 delegationId,
+        uint256 amount,
+        bytes calldata data
+    ) external payable;
+
+    /// @notice Requests to unjail the validator. Caller must pay a fee to prevent spamming.
+    /// Fee must be exact amount.
+    /// @param validatorCmpPubkey 33 bytes compressed secp256k1 public key.
+    /// @param data Additional data for the unjail.
+    function unjail(bytes calldata validatorCmpPubkey, bytes calldata data) external payable;
+}

package/src/interfaces/IUBIPool.sol

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity 0.8.23;
+
+/// @title IUBIPool
+/// @notice Interface for the UBI Pool contract
+interface IUBIPool {
+    /// @notice Emitted when the UBI percentage is set
+    /// @param percentage The percentage of the UBI
+    event UBIPercentageSet(uint32 percentage);
+
+    /// @notice Emitted when the UBI distribution is set
+    /// @param totalUBI The total amount of UBI
+    /// @param validatorCmpPubKeys The validator compressed public keys
+    /// @param amounts The amounts of the UBI for each validator
+    event UBIDistributionSet(uint256 month, uint256 totalUBI, bytes[] validatorCmpPubKeys, uint256[] amounts);
+
+    /// @notice Sets the UBI percentage
+    /// @param percentage The percentage of the UBI
+    function setUBIPercentage(uint32 percentage) external;
+
+    /// @notice Sets the UBI distribution
+    /// @param totalUBI The total amount of UBI
+    /// @param validatorCmpPubKeys The validator compressed public keys
+    /// @param amounts The amounts of the UBI for each validator
+    /// @return distributionId The distribution id
+    function setUBIDistribution(
+        uint256 totalUBI,
+        bytes[] calldata validatorCmpPubKeys,
+        uint256[] calldata amounts
+    ) external returns (uint256);
+
+    /// @notice Claims the UBI for a validator
+    /// @dev The validator address must be the one who is set to receive the UBI
+    /// @param distributionId The distribution id
+    /// @param validatorCmpPubkey The validator compressed public key
+    function claimUBI(uint256 distributionId, bytes calldata validatorCmpPubkey) external;
+}

package/src/interfaces/IUpgradeEntrypoint.sol

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity 0.8.23;
+
+interface IUpgradeEntrypoint {
+    /// PROTO: https://github.com/cosmos/cosmos-sdk/blob/v0.50.9/proto/cosmos/upgrade/v1beta1/upgrade.proto
+    /// @notice Emitted when an upgrade is submitted.
+    /// @param name Sets the name for the upgrade. This name will be used by the upgraded version of the software to
+    /// apply any special "on-upgrade" commands during the first BeginBlock method after the upgrade is applied. It is
+    /// also used to detect whether a software version can handle a given upgrade. If no upgrade handler with this name
+    /// has been set in the software, it will be assumed that the software is out-of-date when the upgrade Time or
+    /// Height is reached and the software will exit.
+    /// @param height The height at which the upgrade must be performed.
+    /// @param info Any application specific upgrade info to be included on-chain such as a git commit that validators
+    /// could automatically upgrade to.
+    event SoftwareUpgrade(string name, int64 height, string info);
+
+    /// @notice Emitted when a planned upgrade is to be cancelled.
+    event CancelUpgrade();
+
+    /// @notice Submits an upgrade plan.
+    /// @param name Sets the name for the upgrade. This name will be used by the upgraded version of the software to
+    /// apply any special "on-upgrade" commands during the first BeginBlock method after the upgrade is applied. It is
+    /// also used to detect whether a software version can handle a given upgrade. If no upgrade handler with this name
+    /// has been set in the software, it will be assumed that the software is out-of-date when the upgrade Time or
+    /// Height is reached and the software will exit.
+    /// @param height The height at which the upgrade must be performed.
+    /// @param info Any application specific upgrade info to be included on-chain such as a git commit that validators
+    /// could automatically upgrade to.
+    function planUpgrade(string calldata name, int64 height, string calldata info) external;
+
+    /// @notice Cancels an upgrade plan if there is one planned. Otherwise, it does nothing.
+    function cancelUpgrade() external;
+}

package/src/libraries/Predeploys.sol

@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity 0.8.23;
+
+/**
+ * @title Predeploys
+ * @notice Predeploy addresses (match story/genutil/evm/predeploys.go)
+ */
+library Predeploys {
+    /// @notice Predeploys
+    /// @dev Address reserved for ERC20 wrapper for Story's native token, address starts with
+    /// Story mainnet chain ID
+    address internal constant WIP = 0x1514000000000000000000000000000000000000;
+
+    /// @dev We reserve the first 1024 addresses after Namespace for proxied predeploys.
+    /// GenerateAlloc.s.sol will set a TransparentUpgradeableProxy for each of them, set to a
+    /// deterministic implementation address. Only named predeploys's implementation will have bytecode, the
+    /// others will be EOAs. Governance will be able to upgrade to valid implementations later if needed.
+    address internal constant Namespace = 0xCCcCCc0000000000000000000000000000000000;
+    /// @dev Number of reserved proxied predeploys in the Namespace.
+    uint256 internal constant NamespaceSize = 1024;
+
+    /// @dev IPTokenStaking proxy address
+    address internal constant Staking = 0xCCcCcC0000000000000000000000000000000001;
+    /// @dev UBIPool proxy address
+    address internal constant UBIPool = 0xCccCCC0000000000000000000000000000000002;
+    /// @dev UpgradeEntryPoint proxy address
+    address internal constant Upgrades = 0xccCCcc0000000000000000000000000000000003;
+
+    /// @notice Create3 factory address https://github.com/ZeframLou/create3-factory
+    /// @dev Since Create3 is deployed using Create2, which is deterministic but depends on the deployer's wallet,
+    /// we use a predeploy to maintain compatibility with the contracts deployed by ZeframLou in a permissionless way.
+    address internal constant Create3 = 0x9fBB3DF7C40Da2e5A0dE984fFE2CCB7C47cd0ABf;
+
+    /// @notice ERC6551Registry address Predeploy
+    /// @dev Common address for the ERC6551Registry across all chains defined by ERC-6551
+    address internal constant ERC6551Registry = 0x000000006551c19487814612e58FE06813775758;
+
+    /// @notice Return true if `addr` is proxied
+    function proxied(address addr) internal pure returns (bool) {
+        return addr > Namespace && addr <= address(uint160(Namespace) + uint160(NamespaceSize));
+    }
+
+    /// @notice Return implementation address for a proxied predeploy
+    function getImplAddress(address proxyAddress) internal pure returns (address) {
+        require(proxied(proxyAddress), "Predeploys: not proxied");
+
+        // max uint160 is odd, which gives us unique implementation for each predeploy
+        return address(type(uint160).max - uint160(proxyAddress));
+    }
+}