Overview

CrossCurve Consensus Bridge (CCB) is a cross-chain communication protocol that enables reliable data and asset transfers between networks without relying on centralized intermediaries.

The system is built on a consensus mechanism among independent cross-chain messaging services, ensuring the authenticity of cross-chain messages received on the destination network.

The goal of CCB is to provide developers with a secure way to connect their dApps, DeFi protocols, DAOs, and Infrastructure Services to a multi-network ecosystem using a standardized API and a minimal set of dependencies.

Architecture

Basic cross-chain schema

The fundamental model of cross-chain interaction has been used in various forms for quite some time.

In blockchain A, a contract calls a bridge contract function to send data to blockchain B. The bridge contract emits an event, which is picked up by its off-chain service. This service then creates a transaction containing the necessary data for the corresponding bridge contract on blockchain B. Upon receiving the transaction, the bridge contract verifies its validity and then invokes the target contract function, passing along the data received from blockchain A.

One of the core challenges lies in the fact that the bridge service operates outside the blockchain environment and therefore cannot be verified on-chain. Different bridge protocols address this issue in different ways.

CrossCurve Consensus Bridge, however, introduces a more comprehensive approach. It is not meant to replace existing protocols - instead, it integrates and leverages their mechanisms, creating a unified and verifiable cross-chain communication layer.

Consensus Bridge schema

• The sender initiates a message in the source network by calling the CrossCurve Gatekeeper contract.

• Depending on the destination chain, the Gatekeeper prepares and executes parallel message dispatches through multiple supported protocols. One of these protocols transmits the full message payload, while the others send verification proofs to confirm message authenticity.

• Each protocol, following its standard cross-chain messaging process, independently delivers its data to the CrossCurve Receiver contract in the destination network.

Advantages

Security

CrossCurve Consensus Bridge provides a truly secure mechanism for cross-chain messaging.

Its minimal configuration requires three sovereign cross-chain protocols.

Even in this base setup, an attacker would need to gain simultaneous control over at least two out of the three protocols to compromise a message — making unauthorized interference practically infeasible.

Censorship Resistance

Decentralization is one of the most effective defenses against censorship.

However, in many cross-chain systems, services are often built on specific infrastructure stacks, which introduces potential points of control and censorship.

CrossCurve Consensus Bridge eliminates this issue by leveraging sovereign protocols that operate independently from one another.

For an adversary to block or alter message delivery through the bridge, they would need to control more than 50% of the protocols participating in the message channel (in the minimal setup, that means controlling two out of three).

Resilience

The consensus of independent protocols ensures not only security but also fault tolerance in message transmission. Even in its minimal configuration, if one of the three protocols becomes temporarily unavailable, the remaining two are sufficient to keep the CrossCurve Consensus Bridge fully operational.

In the rare event of a deadlock — when one or more bridges within the consensus experience prolonged downtime, potentially locking assets that relied on the consensus bridge — the situation remains recoverable. The can replace the affected protocols in the consensus bridge of the impacted chain by approving a dedicated governance proposal.

Governance Protection

The CrossCurve Consensus Bridge is engineered for maximum security through the use of consensus among independent bridge protocols for data transmission.

Yet even the most secure systems can face potential vulnerabilities. The most common vector of attack targets governance mechanisms — an adversary might attempt to alter the composition of participating bridges, making it easier to compromise a single one.

In CrossCurve Consensus Bridge, such a scenario is structurally impossible.

Bridge configuration across all chain pairs is managed exclusively by the CrossCurve DAO. Any modification requires explicit community approval. The voting process lasts 7 days, and even after a proposal passes, the new configuration takes effect only after 24 hours, providing an additional safeguard and ensuring transparent governance.

This underlines the critical role of the CrossCurve DAO in maintaining decentralization across cross-chain messaging.

We believe that greater decentralization and resilience can be achieved when ecosystem participants — those advocating for transparency, stability, and security — become active members of the CrossCurve DAO. Their participation strengthens governance integrity and makes malicious decisions significantly harder to pass.

Capabilities

Cross-Chain Messaging

This is the foundation for building advanced cross-chain applications.

Through the Consensus Bridge, dApps gain a reliable communication layer between their instances deployed across different blockchains - or with APIs of other applications operating in separate networks.

Cross-Chain Token Transfers

Cross-chain token transfer applications using any combination of lock/mint or burn/mint models can rely on the Consensus Bridge as a trustless verification layer.

It provides accurate and verifiable information about token locking, minting, unlocking, or burning events across different blockchains.

Foundation for SuperDVN

The Consensus Bridge integrates seamlessly into the LayerZero cross-chain verification system.

This is achieved through a wrapper module called SuperDVN, which externally behaves like a standard DVN but internally performs multi-protocol consensus verification for enhanced security and reliability.

Supported Protocols

Currently, the CrossCurve Consensus Bridge supports the following messaging protocols:

• CrossCurve Oracle Network

Integration and Connection

The integration with the Consensus Bridge is planned to be permissionless. However, the protocol is currently operating in an experimental mode. If you’d like to connect, please contact us

To send a message to a recipient on another chain, you need to:

1. Prepare the calldata for the target contract function with the required parameters.

2. Call the sendData function on the CrossCurve Gatekeeper contract:

Contracts

To configure the bridge, use the following contract addresses.

Overview

DelegationConditionValidatorV1 This is an upgradeable contract that allows you to set additional conditions for delegating locks. It is integrated with EscrowManager, which allows you to know the current status of the lock when delegating it.

Key Roles and Features:

1. Access Control: Restricts setAssuranceLockParameters and setMinLockVeEywa calls to the owner of contract(owner()).

2. Upgradeable via UUPS: Uses UUPSUpgradeable and OwnableUpgradeable patterns, restricting contract upgrades to the owner.

Inherited Contracts and Interfaces

• UUPSUpgradeable (OpenZeppelin): Provides upgrade functionality under the UUPS proxy pattern, restricted to the contract owner.

• OwnableUpgradeable (OpenZeppelin): Manages ownership, allowing only the owner to modify critical parameters and authorize upgrades.

• IDelegationConditionValidatorV1: Defines core methods (e.g., validateDelegations) and events for this contract.

Additional External References:

• IDelegationManagerV1: Management of delegated locks

• IEscrowManagerExtended: Holds locked token data and checks voting power and freeze logic.

State Variables

• s_escrowManager (IEscrowManagerExtended) IEscrowManager interface for the EscrowManager contract.

• s_delegationManager (IDelegationManagerV1) IDelegationManagerV1 for the DelegationManager contract.

Constructor

• Description: Disables contract initializers to prevent re-initialization in a UUPS proxy context.

External Functions (Defined by IDelegationConditionValidatorV1)

initialize(...)

Description: Configures ownership, references, and initial state:

• References the escrow manager and delegation manager.

Parameters:

• owner_: The address of the contract owner.

• escrowManager_: The IEscrowManager interface for the EscrowManager contract.

• delegationManager_: The IDelegationManagerV1 for the DelegationManager contract.

validateDelegations(address delegator_, address delegatee_, uint256[] calldata tokenIds_)

Description: The function performs checks and determines whether delegation of tokenIds_ from delegator_ to delegatee_ is possible.

Parameters:

• delegator_: The address of the contract owner.

• delegatee_: The IEscrowManager interface for the EscrowManager contract.

• tokenIds_: The IDelegationManagerV1 for the DelegationManager contract.

Checks:

• sender must be a DelegationManager contract. Otherwise, UnauthorizedCaller() is thrown

Errors

• UnauthorizedCaller() Thrown when the caller is not authorized to perform the action.

Summary

DelegationConditionValidatorV1 Being updatable in the long run can provide the opportunity for varied and flexible customization for delegated locks.

Overview

LockHolderV1 is an upgradeable contract integrated with DelegationManager, EscrowManager, EscrowVoteManager, IncentiveRewardsAggregatorV1. For each delegator-delegate pair, a different LockHolder contract is deployed, with delegated locks in the balance. Through the LockHolder contract the proxied call of functions of EscrowManager, EscrowVoteManager counters, as well as collection and distribution of incentive rewards takes place.

Key Roles and Features:

Overview

LockHolderFactoryV1 This is an upgradeable contract that deploys new LockHolder contracts on the blockchain. It is integrated with the DelegationManager contract.

Key Roles and Features:

1. Access Control: Restricts setAssuranceLockParameters and

Overview

CalldataHelperV1 is an upgradeable contract that assists with decoding and slicing transaction calldata. It extracts critical parameters such as method-specific calldata, a target address, and a chain identifier from a given input. This functionality is useful in scenarios where cross-chain calls or proxy calls need to parse custom-encoded calldata.

By implementing ICalldataHelperV1, the CalldataHelperV1 contract ensures a standardized interface for:

• Initializing ownership through an upgradeable pattern.

• Decoding calldata to separate out function-specific parameters from overhead bytes (e.g., selectors).

• Validating slicing operations to prevent out-of-bounds data reads.

Inherited Contracts and Interfaces

• UUPSUpgradeable (OpenZeppelin): Provides functions for upgrading this contract in a UUPS proxy setup, ensuring only the owner can authorize upgrades.

• OwnableUpgradeable (OpenZeppelin): Implements ownership-related logic, allowing only the contract owner to perform certain actions.

• ICalldataHelperV1: Declares the initialize and decode functions, as well as the InvalidSliceParameters error.

Constants and State Variables

This contract does not introduce new constants besides those inherited or implied from the interface. It also does not maintain any additional state variables beyond upgradeability and ownership structures provided by OpenZeppelin libraries.

Constructor

• Description:

  • Disables initializers to ensure this upgradeable contract cannot be re-initialized after deployment, following best practices for UUPS proxy pattern.

External Functions

initialize(address owner_)

• Description:

  • Initializes the contract in an upgradeable context.

  • Sets up ownership by transferring ownership to the specified owner_.

  • Can only be called once due to the

decode(bytes calldata calldata_)

• Description:

  • Decodes the provided calldata to extract three main elements:

    1. m_calldata: The method-specific or function-specific bytes of calldata.

Internal and Private Functions

_authorizeUpgrade(address)

• Description:

  • Restricts contract upgrades so that only the owner may authorize them, protecting upgrade logic from unauthorized calls.

_slice(bytes memory data_, uint256 start_, uint256 length_)

• Description:

  • Extracts a slice from data_ starting at offset start_ for length_ bytes.

  • Reverts with InvalidSliceParameters if out-of-bounds.

Errors

InvalidSliceParameters()

• Description: Indicates that the requested slice exceeds the bounds of the original array (start_ + length_ > data_.length).

Summary

CalldataHelperV1 provides a lightweight, upgradeable solution for parsing transaction calldata and extracting specific parameters like function-specific calldata, target addresses, and chain IDs. It integrates with standard libraries for safe upgradeability (UUPSUpgradeable) and ownership control (OwnableUpgradeable), ensuring secure and maintainable deployment. By strictly enforcing slice parameter checks and skipping the initial 4 bytes, CalldataHelperV1 simplifies the process of handling custom-encoded transaction data in cross-chain or proxied contexts.

Overview

Treasury is a minimal yet crucial smart contract that securely stores and allows controlled withdrawals of both native ETH and ERC20 tokens. Owned by a single address, it enforces strict access control on asset movements via onlyOwner and mitigates re-entrant calls through nonReentrant. This design ensures that only the contract owner can authorize withdrawals and that no re-entrancy exploits can siphon funds.

Key Attributes:

1. Custody of Funds: Holds ERC20 tokens and ETH in a secure manner.

2. Restricted Withdrawals: Only the contract’s owner can withdraw funds, specifying the token address, amount, and recipient.

3. Non-Reentrant Calls: Uses ReentrancyGuard to prevent complex re-entrancy exploits during withdrawals.

By implementing the ITreasury interface, Treasury provides a standardized API (the withdraw function) and emits an event (TokenWithdrawn) whenever funds are moved out.

Inherited Contracts and Interfaces

• Ownable (OpenZeppelin) Allows the contract to have an owner who can perform restricted operations. In this case, only the owner can call withdraw.

• ReentrancyGuard (OpenZeppelin) Protects critical functions from re-entrancy attacks. The withdraw function uses the nonReentrant modifier.

• ITreasury (Custom Interface) Declares the withdraw

Additional External References:

• SafeERC20, IERC20 (OpenZeppelin): Used to safely transfer ERC20 tokens in the withdraw function.

• Address (OpenZeppelin): Provides the sendValue method for securely transferring ETH.

State Variables

The Treasury contract does not introduce mutable storage variables beyond those inherited from its parent classes. However, it defines:

• owner (Ownable.sol) A variable inherited from Ownable indicating the contract owner. Managed internally by the Ownable library’s _owner storage variable.

No other custom state variables are defined. The contract relies on the OpenZeppelin libraries for ownership tracking and reentrancy control.

Constructor

• Description: The constructor takes a single parameter, owner_, which designates the address to be assigned as the contract owner via Ownable. This ownership implies exclusive access to withdraw.

• Parameters:

  • owner_: The address that will be granted ownership of the contract upon deployment.

Fallback Function

• Description: A receive fallback function that allows the contract to accept native ETH transfers (e.g., via send or transfer with no calldata). This function does not store or otherwise process the ETH, aside from receiving it into the contract’s balance.

External Functions

withdraw(address token_, uint256 amount_, address recipient_)

• Description: Allows the contract owner to withdraw either an ERC20 token or native ETH from the treasury to a specified recipient_. If token_ is the zero address (address(0)), it indicates a withdrawal of ETH. Otherwise, it withdraws the specified ERC20 token using a safe transfer.

• Parameters:

  • token_

Events

TokenWithdrawn(address indexed token, uint256 indexed amount, address indexed recipient)

• Emitted When: The withdraw function completes successfully, whether removing ETH or ERC20 tokens.

• Parameters:

  • token: The address of the token being withdrawn. Zero address if ETH.

Summary

Treasury acts as a straightforward contract for securely holding and releasing ETH or ERC20 tokens under the CrossCurve ecosystem. With Ownable restricting withdraw calls to the contract owner and ReentrancyGuard ensuring robust security, the Treasury provides a trustworthy store for tokens:

1. Secure Custody: Only an authorized owner can move assets out.

2. Versatile Withdrawals: Supports both ETH and arbitrary ERC20 tokens using standardized SafeERC20 operations.

3. Transparent Logging: The TokenWithdrawn event ensures on-chain traceability of funds outflow.

This minimal approach ensures clarity, security, and traceable control over treasury assets within the CrossCurve framework.

Overview

RewardsDistributorFactoryV1 is an upgradeable contract (using UUPS) that deploys new instances of IncentiveRewardsDistributor. It restricts calls to createRewardsDistributor such that only the escrow vote manager can request a new distributor, thus ensuring controlled creation of additional reward distribution contracts.

Key Roles and Features:

Overview

GaugeFactoryV1 is an upgradeable factory contract responsible for deploying and initializing Gauge contracts within the CrossCurve ecosystem. These gauges are used to manage and distribute rewards for various liquidity pools or other vote-driven incentives. The factory integrates with an Escrow Vote Manager to ensure that only the authorized vote manager can create new gauges, thus maintaining a secure and controlled environment for gauge deployments.

Key Roles and Features:

1. Gauge Deployment: Deploys a new GaugeV1 instance as an upgradeable proxy (using ERC1967Proxy), specifying an implementation, an owner, and initial parameters for reward distribution campaigns.

2. Access Control: Restricts createGauge calls to the escrow vote manager (s_escrowVoteManager).

3. Upgradeable via UUPS: Uses UUPSUpgradeable and OwnableUpgradeable patterns, restricting contract upgrades to the owner.

By implementing IGaugeFactoryV1, GaugeFactoryV1 provides a standardized interface and event structure for gauge creation, enabling other contracts in the CrossCurve ecosystem to request new gauges securely.

Inherited Contracts and Interfaces

• UUPSUpgradeable (OpenZeppelin): Provides upgrade functionality using the UUPS proxy pattern. Only the owner can authorize upgrades.

• OwnableUpgradeable (OpenZeppelin): Establishes ownership and restricts certain critical functions (like upgrades) to the contract owner.

• IGaugeFactoryV1: Declares functions (initialize and createGauge) and the GaugeCreated event. Also defines the InvalidCaller

Additional External References:

• ERC1967Proxy (OpenZeppelin): A proxy implementation that stores the logic contract address in storage per EIP-1967.

• IDistributionCreator.CampaignParameters: Used to initialize reward distribution parameters for newly created gauges.

• GaugeV1: The gauge implementation contract being deployed as a proxy.

State Variables

• s_escrowVoteManager (address): The address of the escrow vote manager contract authorized to create new gauges. Only s_escrowVoteManager can call the createGauge function.

Constructor

• Description: Disables initializers to prevent re-initialization in a UUPS upgradeable setup. Ensures the initialize function can only be called once.

External Functions

initialize(...)

• Description: Initializes the factory contract by setting the contract owner (owner_) and the escrow vote manager (escrowVoteManager_). This function can only be called once due to the initializer modifier.

• Parameters:

  • owner_

createGauge(...)

• Description: Deploys and initializes a new GaugeV1 contract as an ERC1967Proxy, passing in the gauge implementation address, initialization arguments, and returning the newly created gauge address.

• Parameters:

  • owner_: The address that will become the owner of the new gauge contract.

Internal Functions

_authorizeUpgrade(address)

• Description: Restricts the contract’s upgrade function (in a UUPS proxy context) to the owner, ensuring unauthorized parties cannot upgrade the factory logic.

Events

GaugeCreated(address indexed gauge, address indexed implementation)

• Emitted When: A new gauge contract is deployed via createGauge.

• Parameters:

  • gauge: The address of the newly created gauge (proxy).

Errors

InvalidCaller()

• Description: Thrown if createGauge is called by an address other than s_escrowVoteManager. Ensures gauge creation is limited to the authorized escrow vote manager.

Summary

GaugeFactoryV1 securely and upgradeably deploys GaugeV1 contracts under the control of the escrow vote manager. By enforcing that only the designated manager can call createGauge, it prevents unauthorized deployments while still allowing flexible, time-extended reward distribution campaigns. The combination of UUPS upgradeability, ownership checks, and a standardized creation event (GaugeCreated) supports a robust, maintainable environment for launching new gauges in the CrossCurve ecosystem.

Overview

GaugeV1 is an upgradeable contract used to manage reward distributions for a particular pool or strategy in the CrossCurve ecosystem. The contract primarily integrates with the Escrow Vote Manager (s_escrowVoteManager) to authorize reward notifications and uses a Distribution Creator (DISTRIBUTION_CREATOR) for executing reward distribution campaigns.

Key features include:

• Upgradeable (UUPS Pattern): The contract can be updated while preserving state.

• Owner-Based Access Control: Critical functions (like upgrading the contract and updating campaign parameters) are restricted to the owner.

• Reward Notification: The notifyRewardAmount function can only be invoked by the authorized escrow vote manager, ensuring a controlled flow of rewards.

• Campaign Parameters: The gauge uses dynamic campaign parameters (s_campaignParameters) to manage reward distribution schedules and amounts, which can be updated by the owner if needed.

By implementing IGaugeV1, GaugeV1 provides a standardized interface for initializing, updating campaign parameters, and receiving new reward amounts within the CrossCurve ecosystem.

Inherited Contracts and Interfaces

• UUPSUpgradeable (OpenZeppelin): Enables upgradeability under the UUPS (Universal Upgradeable Proxy Standard) pattern, restricted to the contract owner.

• OwnableUpgradeable (OpenZeppelin): Provides ownership logic, limiting certain state changes (e.g., upgrading, updating parameters) to the contract owner.

• IGaugeV1: Interface defining core functions (e.g., initialize, updateCampaignParameters, notifyRewardAmount) and events (

Additional External References:

• SafeERC20, IERC20 (OpenZeppelin): Library and interface for safe ERC20 token transfers.

• IEscrowVoteManagerV1: Tracks and authorizes reward notifications, ensuring that only the designated manager can call notifyRewardAmount.

• IDistributionCreator: Contract on Arbitrum that actually creates or schedules distribution campaigns (Merkl distributions).

Constants

• EPOCH_DURATION: The duration of an epoch (1 week). Used to align reward distribution campaigns with discrete time intervals.

• DISTRIBUTION_CREATOR: The address of the Merkl distribution contract on Arbitrum. This contract is responsible for orchestrating reward distributions once campaigns are created.

State Variables

• s_escrowVoteManager (address) Address of the escrow vote manager contract, which is authorized to call notifyRewardAmount.

• s_eywa (address) The EYWA token address used for rewards distribution.

• s_campaignParameters (IDistributionCreator.CampaignParameters) Holds the current campaign parameters for distributing rewards. These parameters include data like amount, duration, start timestamp, and distribution logic, which can be updated by the owner.

Constructor

• Description: Disables contract initializers to prevent multiple initializations. Enforces that initialize can be called only once in a UUPS upgradeable context.

External Functions

initialize(...)

• Description:

  • Initializes the gauge contract by setting the owner, escrow vote manager, EYWA token address, and the initial campaign parameters for rewards.

  • Can only be called once, marked by the initializer modifier from OpenZeppelin upgradeable patterns.

updateCampaignParameters(...)

• Description:

  • Allows the contract owner to update the gauge’s campaign parameters.

  • The newly provided parameters (newCampaignParameters_) overwrite the existing ones in s_campaignParameters.

notifyRewardAmount(uint256 amount_)

• Description:

  • Notifies the gauge of a newly available amount_ of EYWA tokens to be distributed as rewards.

  • Can only be called by s_escrowVoteManager.

Internal and Private Functions

_authorizeUpgrade(address)

• Description:

  • Ensures that only the contract owner can authorize upgrades.

  • Enforced by the UUPSUpgradeable pattern.

Events

1. RewardNotified(uint256 indexed amount)

   • Emitted when new rewards are notified to the gauge, indicating the total tokens added.

2. CampaignParametersUpdated( address indexed gauge, IDistributionCreator.CampaignParameters oldCampaignParameters, IDistributionCreator.CampaignParameters newCampaignParameters )

Errors

• UnauthorizedCaller()

  • Thrown if a function restricted to s_escrowVoteManager or onlyOwner is called by an unauthorized address.

Summary

GaugeV1 is an upgradeable contract that manages reward distributions for a specific pool or strategy within the CrossCurve ecosystem. By connecting to an Escrow Vote Manager, it ensures only authorized parties can add new rewards (notifyRewardAmount). Through DistributionCreator on Arbitrum, it transforms these rewards into time-bound distribution campaigns. The contract owner can update campaign parameters if needed, while all major functionalities (initialization, upgrade, parameter updates) remain protected by ownership and authorized checks.

Overview

EscrowVoteManagerV1 is a governance-related contract that manages gauge creation, voting power distribution, reward claiming, and other functionalities within the CrossCurve ecosystem. It integrates with:

• Escrow Manager (IEscrowManager): Tracks locked EYWA positions.

• Emission Manager (IEmissionManagerV1): Supplies emission epochs and total reward amounts.

• Rewards Distributor Factory (IRewardsDistributorFactoryV1): Deploys incentive reward distributor contracts for new gauges.

• Gauge Factory (IGaugeFactoryV1): Deploys gauge contracts, which are used to distribute rewards based on votes.

• Reward Distributors (IRewardsDistributor): Handle depositing and withdrawing of votes and distributing claimable incentives.

The contract also includes logic for:

1. Voting with multiple token IDs: A user can cast votes across multiple locks (NFTs) for multiple pools.

2. Transfer Freeze after Deboost: Adds a cooldown period preventing NFT transfers after a lock has been deboosted in the Escrow Manager.

3. Gauge Lifecycle Management: Owners can create, kill, or revive gauges.

4. Reward Distribution: Accumulates gauge rewards and distributes them after each epoch.

By implementing IEscrowVoteManagerV1, EscrowVoteManagerV1 provides a standardized API for gauge-based governance interactions in the CrossCurve ecosystem.

Inherited Contracts and Interfaces

• UUPSUpgradeable (OpenZeppelin): Provides upgrade functionality under the UUPS proxy pattern, restricted to the contract owner.

• OwnableUpgradeable (OpenZeppelin): Manages ownership, allowing only the owner to modify critical parameters and authorize upgrades.

• IEscrowVoteManagerV1: Defines core methods (e.g., vote, createGauge, distributeRewardsForMultipleGauges) and events for this contract.

Additional External References:

• SafeERC20, IERC20 (OpenZeppelin): Handles secure ERC20 operations for distributing and approving token transfers.

• Math (OpenZeppelin): Provides utility math functions, e.g., Math.max.

• IEscrowManager: Holds locked token data and checks voting power and freeze logic.

Constants

• EPOCH_DURATION: Duration of each emission/gauge epoch (1 week).

• PRECISION: Scaling factor (1e18) for reward calculations and distribution indexes.

State Variables

• s_transferFreezeAfterDeboost (uint256) Duration (in seconds) that locks are non-transferable after a deboost in the Escrow Manager.

• s_emissionManager (address) Address of the emission manager contract, which calls this manager to notify new rewards.

• s_eywa (address) Address of the EYWA token used for gauge rewards.

Constructor

• Description: Disables contract initializers to prevent re-initialization in a UUPS proxy context.

External Functions (Defined by IEscrowVoteManagerV1)

initialize(...)

Description: Configures ownership, references, and initial state:

• Sets s_transferFreezeAfterDeboost to 4 hours initially.

• References the emission manager, escrow manager, gauge/rewards distributor factories, and whitelists initial tokens.

updateTransferFreezeAfterDeboost(uint256 transferFreezeAfterDeboost_)

Description: Updates the freeze period (in seconds) that applies after a deboost in Escrow Manager. This restricts NFT transfers for transferFreezeAfterDeboost_ seconds.

Events:

• Emits TransferFreezeAfterDeboostUpdated(oldDuration, newDuration).

createGauge(address pool_, IDistributionCreator.CampaignParameters calldata campaignParameters_)

Description: Creates a new gauge for a specified pool by:

1. Deploying an incentive rewards distributor via s_rewardsDistributorFactory.

2. Deploying a gauge contract via s_gaugeFactory.

3. Tracking the new gauge and marking it as active.

Checks:

• Ensures the pool does not already have a gauge.

Events:

• Emits GaugeCreated(pool_, gauge, incentiveRewardsDistributor).

killGauge(address gauge_)

Description: Deactivates a gauge so it stops receiving future rewards. Does not remove votes or claimable rewards; simply marks it inactive.

Checks:

• s_isActiveGauge[gauge_] must be true.

Events:

• Emits GaugeKilled(gauge_).

reviveGauge(address gauge_)

Description: Reactivates a previously killed gauge, allowing it to receive rewards again.

Checks:

• s_isActiveGauge[gauge_] must be false.

Events:

• Emits GaugeRevived(gauge_).

setWhitelistStatusForTokens(address[] calldata tokens_, bool[] calldata statuses_)

Description: Updates whether tokens are whitelisted for reward distribution. Only callable by the contract owner. Checks input array lengths.

Events:

• Emits WhitelistStatusUpdatedForTokens(operator, tokens_, statuses_).

vote(uint256[] calldata tokenIds_, address[][] calldata pools_, uint256[][] calldata weights_)

Description: Allows a user to cast votes for multiple token IDs across multiple pools. For each token ID:

1. Authorizes caller via IEscrowManager.checkAuthorized.

2. Validates array lengths for pools and weights.

3. Performs _vote(...) to reset old votes, allocate new votes, and update vote counts.

reset(uint256 tokenId_)

Description: Removes all existing votes for a given token ID, setting them to zero. The caller must be authorized. Updates the token’s last vote timestamp.

poke(uint256 tokenId_)

Description: Recalculates (re-casts) votes for a token ID based on updated voting power without changing the vote distribution pattern. The function still calls _vote(...) internally using the same pools and weights previously allocated.

claimIncentives(address[] calldata incentiveRewardsDistributors_, address[][] calldata rewardTokens_)

Description: Claims incentives for the caller from multiple rewards distributors. Each distributor has a list of reward tokens. Forwards the call to IRewardsDistributor.getReward.

notifyRewardAmount(uint256 rewardAmount_)

Description: Only callable by s_emissionManager. Increments _s_distributionIndex by an amount proportional to rewardAmount_ / totalVotesInPreviousEpoch. If no votes or unauthorized call, reverts.

Events:

• Emits RewardNotified(rewardAmount_).

distributeRewardsForMultipleGauges(address[] calldata gauges_)

Description: Triggers an epoch update in the emission manager, then calls _distributeRewards(...) for each gauge in gauges_.

distributeRewardsForGaugesInRange(uint256 start_, uint256 end_)

Description: Also triggers an emission manager epoch update, then iterates through s_pools[start_ ... end_] to distribute rewards to each gauge.

getPoolsCount()

Description: Returns the number of pools (and thus gauges) tracked in s_pools.

nextEpochStart()

Description: Returns the next epoch’s start time as s_currentEpochStart + EPOCH_DURATION from the emission manager.

currentEpochStart()

Description: Returns the current epoch’s start time from the emission manager.

Internal and Private Functions

_authorizeUpgrade(address)

Description: Restricts contract upgrades to the owner.

_vote(...)

Description: Handles the actual voting steps for a single token ID:

1. Calls _reset(...) to remove existing votes.

2. Proportionally allocates votingPower_ across pools based on weights_.

3. Updates s_votesByEpochAndPool, s_votesByTokenIdAndPool, and s_votedPoolsByTokenId

Events:

• VoteCast on each pool voted for.

_reset(uint256 tokenId_)

Description: Clears existing votes for tokenId_ by:

• Withdrawing votes from all previously voted pools (if the token voted in the current epoch).

• Adjusting s_votesByEpochAndPool and s_votesByTokenIdAndPool.

• Updating the total votes for the epoch.

_distributeRewards(address gauge_, uint256 currentEpochStart_)

Description: Distributes claimable EYWA tokens to a specified gauge. If the gauge is inactive, does nothing. Otherwise:

1. Calls _updateRewardIndexForGauge(...).

2. Notifies the gauge of claimable rewards via notifyRewardAmount.

Events:

• RewardsDistributed after successful distribution.

_updateRewardIndexForGauge(address gauge_, uint256 currentEpochStart_)

Description: Calculates how many new tokens a gauge can claim using the global distribution index. If there were votes in the previous epoch (currentEpochStart_ - EPOCH_DURATION), the gauge's share of _s_distributionIndex is updated, and claimable rewards are added to s_claimableRewardsByGauge[gauge_].

Events

• TransferFreezeAfterDeboostUpdated(oldDuration, newDuration) Emitted when the freeze period is changed.

• GaugeCreated(pool, gauge, incentiveRewardsDistributor) Emitted upon successful gauge creation.

• GaugeKilled(gauge), GaugeRevived(gauge) Emitted when a gauge is deactivated or reactivated.

Errors

• GaugeDoesNotExist() Thrown if a user tries to vote for a gauge that is not known (no gauge for that pool).

• GaugeAlreadyExists() Thrown when creating a gauge for a pool that already has one.

• GaugeNotActive() Thrown if an action (like voting or distributing) is attempted on an inactive gauge.

Summary

EscrowVoteManagerV1 orchestrates multi-token, multi-pool voting within the CrossCurve ecosystem. By coordinating gauges, incentive reward distribution, epoch-based reward notifications from the emission manager, and freeze logic from the escrow manager, it ensures a secure, transparent mechanism for users to direct token emissions to liquidity pools and other incentive-based programs. With features like deboost freeze periods and gauge lifecycle control, the contract provides flexible governance and reward distribution for token holders.

Overview

RebaseRewardsDistributorV1 is an upgradeable contract that distributes rebase rewards to veEYWA token holders (locks) in the CrossCurve ecosystem. It relies on an Emission Manager (s_emissionManager) to trigger epoch updates (checkpoints) and fetches locked token data from an Escrow Manager (s_escrowManager). The contract tracks weekly reward distributions and lets veEYWA token holders claim these rebase rewards either directly (if their lock is expired) or by depositing rewards back into the lock (if it’s still active).

Key features include:

Overview

EscrowManager is a smart contract that manages locked EYWA tokens, each represented by a unique ERC-721 NFT (sometimes referred to as a "veEYWA" token). Each lock NFT stores information about its locked token amount, unlock time, vesting wallets, and booster NFTs. The contract supports operations like depositing, boosting, extending, deboosting, and withdrawing locked tokens, while tracking voting power via time-based checkpoints and epochs. It integrates with an external vote manager contract for governance operations and a collection contract for booster NFTs.

Key Features:

1. Lock Creation & Management: Users can create locks by transferring EYWA tokens, vesting wallets, or tokens from an NFT collection. They can add more tokens, apply boosters, or extend the lock duration.

2. Voting Power: Each lock corresponds to voting power that evolves over time. The contract records checkpoints of ownership and calculates voting weights using a dynamic rate-of-change approach.

3. Booster Mechanism: Boosters from the collection can increase a lock’s "coverage," thus effectively increasing its lock amount for voting power calculations.

4. Cooldown & Freeze Logic: After certain actions such as deboosting, token transfers may be temporarily frozen to prevent immediate re-deposit or locking manipulations.

5. Delegation Checks: The contract can integrate with a delegation manager to move voting power between addresses.

By implementing the IEscrowManager interface, the EscrowManager contract provides a consistent API for user and external contract interactions in the CrossCurve ecosystem.

Inherited Contracts and Interfaces

• ERC721Enumerable, ERC721 (OpenZeppelin): Provides standard ERC-721 NFT functionality with enumeration capabilities, enabling easy listing of all minted NFTs.

• ERC721Holder (OpenZeppelin): Allows the contract to safely hold ERC-721 tokens (necessary when receiving booster NFTs).

• ReentrancyGuard (OpenZeppelin): Mitigates re-entrant calls on state-changing functions.

• SafeERC20, IERC20 (OpenZeppelin):

External Interfaces:

• IEscrowManager: The interface implemented by this contract, defining locking and booster logic.

• IEscrowVoteManagerV1: The vote manager that tracks epochs, triggers freeze logic, and notifies about gauge rewards.

• ICollection, IWalletFactory, IVestingWallet: Components in the ecosystem for NFT boosters, creating/managing vesting wallets, and bridging custom data.

• IMetadataProviderV1:

Constants

• ATTACHMENTS_LIMIT = 100 Maximum number of attachments (vesting wallets or booster NFTs) allowed per lock.

• EPOCH_DURATION = 1 weeks Governs epoch-based calculations for voting power and lock logic.

• MAXIMUM_LOCK_DURATION = 156 weeks Maximum allowed lock duration in seconds (approximately 3 years).

Immutable Addresses:

• ESCROW_VOTE_MANAGER (address): The escrow vote manager contract address.

• DELEGATION_MANAGER (address): The delegation manager contract address.

• EYWA (IERC20): The EYWA token used in locking.

State Variables

• s_nextTokenId (uint256) The next NFT token ID to be minted.

• s_epoch (uint256) Tracks how many epochs have occurred, updated whenever lock states change significantly.

• s_totalLocked (uint256) Total EYWA tokens locked across all positions.

Lock and Booster Details:

• _s_lockInfoByTokenId (mapping(uint256 => LockInfo)): Internal mapping of lock data.

• s_pureLockAmountByTokenId, s_vestingWalletsLockAmountByTokenId: Track base token amounts and vesting wallet contributions.

• s_currentCoverageByTokenId: Booster coverage for each lock.

Checkpointing and Voting:

• s_checkpointsNumberByAccount (mapping(address => uint32)): Number of checkpoints for each account.

• s_checkpoints (mapping(address => mapping(uint32 => Checkpoint))): Account checkpoints listing owned lock NFTs at different times.

• s_ownershipChangeBlockNumberByTokenId (mapping(uint256 => uint256)): Block number of the last ownership change for each NFT (prevents double-voting in the same block).

Deboost and Freeze Logic:

• s_lastDeboostTimestampByTokenId (mapping(uint256 => uint256)): Records the last time a token was deboosted, used to freeze subsequent transfers.

Constructor

• Description: Deploys the EscrowManager, sets immutable addresses for the escrow vote manager, delegation manager, EYWA token, collection, wallet factory, and metadata provider, and initializes the NFT name and symbol.

External Functions (Defined by IEscrowManager)

createLock(uint256 lockAmount_, uint256 lockDuration_, address recipient_)

Description: Creates a lock by transferring lockAmount_ of EYWA from the caller, locking it for lockDuration_ (rounded down to epoch boundaries). Mints an NFT for recipient_.

createLock(uint256 lockDuration_, address recipient_, address[] calldata vestingWallets_)

Description: Creates a lock by transferring tokens from multiple vesting wallets owned by the caller, then mints an NFT lock. Each vesting wallet's beneficiary must match the caller.

createLock(uint256 lockDuration_, address recipient_, uint256[] calldata collectionTokenIds_)

Description: Creates a lock using tokens associated with the given collection token IDs. Collects vesting wallets pinned to those NFTs, locks their balances, and automatically applies boosters via _modifyBoost.

deposit(uint256 tokenId_, uint256 lockAmount_)

Description: Adds extra EYWA to an existing lock. Requires caller authorization (_checkAuthorized).

depositFor(uint256 tokenId_, uint256 lockAmount_)

Description: Adds EYWA to an existing lock on behalf of the owner, without caller checks.

boost(uint256 tokenId_, uint256[] calldata collectionTokenIds_)

Description: Associates additional booster NFTs with a lock, increasing its coverage and potentially its voting power. Booster NFTs may also bring vesting wallets if pinned.

deboost(uint256 tokenId_, uint256[] calldata collectionTokenIds_)

Description: Removes booster NFTs from a lock. Verifies that the token hasn't voted in the current epoch. Records the block timestamp in s_lastDeboostTimestampByTokenId to freeze transfers for a defined period.

withdraw(uint256 tokenId_)

Description: Withdraws the tokens from an expired lock, returning booster NFTs, transferring vesting wallets, and burning the lock NFT. The caller must be authorized.

Events:

• Emits LockWithdrawn(recipient, tokenId, value) upon completion.

extend(uint256 tokenId_, uint256 lockDuration_)

Description: Extends the lock duration to a new unlockTime. Must be strictly greater than the current one. Updates voting power.

setVoteStatus(uint256 tokenId_, bool status_)

Description: Only callable by ESCROW_VOTE_MANAGER. Marks a token as having voted or not.

registerTokenVote(uint256 tokenId_, bool status_)

Description: Only callable by ESCROW_VOTE_MANAGER. Records that a token has voted (or not) in the current epoch.

moveVotes(uint256 tokenId_, address from_, address to_)

Description: Called by DELEGATION_MANAGER to transfer voting power if delegated. Ensures the token exists.

getLockInfoByTokenId(uint256 tokenId_)

Description: Returns the lock’s current amount, unlock timestamp, and associated vesting wallets.

getRemainingFreezeTimeByTokenId(uint256 tokenId_)

Description: Reports how many seconds remain until a token can be transferred again after deboost. Returns 0 if the freeze period has elapsed.

getCheckpoint(address account_, uint32 index_)

Description: Retrieves the checkpoint at index_ for account_, listing token ownership at that historical checkpoint.

getPastVotes(address account_, uint256 timestamp_)

Description: Calculates an account’s total voting power at a previous timestamp_, summing the power of all tokens they held at that time.

getTotalSupply()

Description: Returns the total voting power across all locks at the current time.

getPastTotalSupply(uint256 timestamp_)

Description: Returns the total voting power at a specific timestamp_. Uses the VotingPowerHelper for historical calculations.

getPastVotesByTokenId(uint256 tokenId_, uint256 timestamp_)

Description: Computes a single token’s voting power at a past timestamp_, factoring in rate-of-change data.

getBoostersByTokenId(uint256 tokenId_)

Description: Lists all booster NFT IDs currently enhancing the lock identified by tokenId_.

checkAuthorized(address owner_, address spender_, uint256 tokenId_)

Description: Checks if spender_ is permitted (owner, approved address, or operator) to manage the NFT for tokenId_.

exists(uint256 tokenId_)

Description: Returns true if an NFT for tokenId_ has been minted (i.e., the lock exists).

Internal and Private Functions

_createLock(...)

Signature:

Description: Core logic for creating a new lock. Mints an NFT, stores lock info, and transfers tokens or vesting wallets if needed.

_deposit(...)

Signature:

Description: Adds more EYWA to a lock, updating voting power calculations.

_modifyBoost(...)

Signature:

Description: Adds or removes booster NFTs to/from a lock. Adjusts coverage and recalculates voting power accordingly.

_updateLock(...)

Signature:

Description: Recomputes and stores new voting power points whenever a lock’s amount or unlock time changes. Adjusts historical checkpoints and the global epoch.

_moveVotes(...)

Signature:

Description: Reassigns voting power from from_ to to_ if the NFT’s ownership changes. Creates or updates checkpoints for both addresses.

_clearStorage(...)

Signature:

Description: Clears all references and data for a withdrawn or burned lock, freeing storage.

_findCheckpoint(...)

Signature:

Description: Helper to find or create the index for a checkpoint at the current timestamp for a given account.

_calculateModifiedLockAmount(...)

Signature:

Description: Calculates the final lock amount after factoring in booster NFT coverage and rarity-based multipliers. If coverage exceeds lock amount, the algorithm partial-applies boosters in descending rarity.

Events

LockWithdrawn(address indexed recipient, uint256 indexed tokenId, uint256 indexed value)

Emitted When: A user withdraws tokens from an expired lock. The NFT is burned, and booster NFTs/vesting wallets are returned.

Errors

• InvalidBeneficiary()

• InvalidVestingWallet()

• InvalidLockDuration()

These errors ensure that contract rules regarding lock durations, amounts, boosters, freeze periods, and ownership checks are strictly enforced.

Summary

EscrowManager provides a robust system for locking EYWA tokens in exchange for NFT-based positions (veEYWA). Each lock can combine direct token transfers, vesting wallets, and booster NFTs, forming dynamic voting power that evolves over time. Freeze periods after deboosts and careful checkpointing logic protect against immediate manipulations of lock amounts and ownership. Through a clear interface defined in IEscrowManager, external ecosystem components (e.g., delegation managers, vote managers, NFT collections) can seamlessly integrate with this locking mechanism to support governance, incentive distribution, and user engagement within the CrossCurve platform.

Overview

IncentiveRewardsDistributor is a contract that builds upon an abstract RewardsDistributor to manage the distribution of incentive rewards within the CrossCurve ecosystem. The RewardsDistributor base contract provides fundamental logic for tracking deposits, withdrawals, reward notifications, and reward claims over discrete epochs. The IncentiveRewardsDistributor adds:

1. Whitelisting of Tokens: Before accepting a new token as a reward token, it checks with the escrow vote manager to ensure it is whitelisted.

2. Escrow Vote Manager Authorization: Restricts calls to certain functions (like getReward) to only the authorized vote manager.

3. Inheritance and Extended Logic: Integrates seamlessly with the epoch-based deposit/withdraw system in RewardsDistributor to finalize reward amounts and calculations.

By implementing IIncentiveRewardsDistributor, this contract conforms to a standard reward distributor interface used throughout the CrossCurve ecosystem.

Inherited Contracts and Interfaces

• RewardsDistributor (Abstract Contract):

  • Manages core reward distribution functionality, such as:

    • Tracking how many tokens each owner has deposited during a specific epoch.

    • Storing how many rewards are allocated to a token for each epoch.

Additional External References:

• IEscrowVoteManagerV1:

  • Provides s_isWhitelistedToken to validate new reward tokens.

  • Acts as an authorization gate for methods that require msg.sender to be the vote manager.

Contract Architecture

Inherited from RewardsDistributor

The base RewardsDistributor constructor sets immutable references for ESCROW_VOTE_MANAGER and ESCROW_MANAGER. It also defines the following main categories of functionality:

1. Epoch-Based Deposit and Withdrawal:

   • deposit(uint256 amount_, uint256 tokenId_)

   • withdraw(uint256 amount_, uint256 tokenId_)

We now detail each of these base functions.

Functions in the Base Contract: RewardsDistributor

1. Constructor

• Description: Sets ESCROW_VOTE_MANAGER and ESCROW_MANAGER as immutable addresses, used for authorization and lock ownership lookups.

• Parameters:

  • escrowVoteManager_: The address of the escrow vote manager contract.

2. deposit(uint256 amount_, uint256 tokenId_)

• Description:

  • Called by the escrow vote manager to record that amount_ of tokens have been deposited for the lock represented by tokenId_ in the current epoch.

  • Increments the total supply and the lock owner’s balance for the current epoch.

3. withdraw(uint256 amount_, uint256 tokenId_)

• Description:

  • Called by the escrow vote manager to record that amount_ of tokens have been removed from the lock represented by tokenId_ in the current epoch.

  • Decrements the total supply and the lock owner’s balance for the current epoch.

4. getRewardTokensCount()

• Description: Returns the length of the s_rewardTokens array, i.e., how many reward tokens the distributor currently recognizes.

• Return:

  • uint256: number of recognized reward tokens.

5. earned(address owner_, address rewardToken_)

• Description:

  • Computes how many tokens of rewardToken_ the owner_ has earned across epochs since their last claim.

  • Iterates through epochs in weekly increments up to a maximum of 52 (1-year look-back) or until reaching the current epoch.

6. earnedByEpoch(address owner_, address rewardToken_, uint256 epoch_)

• Description:

  • Returns how many rewardToken_ tokens were earned by owner_ specifically in a single epoch.

  • Calculated as rewardPerToken(rewardToken_, epoch_) * s_balanceByOwnerAndEpoch[owner_][epoch_] / 1e18.

7. rewardPerToken(address rewardToken_, uint256 epoch_)

• Description:

  • Calculates the distribution ratio for rewardToken_ in a given epoch_.

  • If s_totalSupplyByEpoch[epoch_] is zero, it simply returns s_rewardAmountByTokenAndEpoch[rewardToken_][epoch_].

8. getReward(address owner_, address[] calldata rewardTokens_) (abstract)

• Description:

  • Abstract in the base RewardsDistributor. The child contract (IncentiveRewardsDistributor) provides the actual implementation.

  • Child’s implementation calls _getReward(...) internally after verifying authorization.

9. notifyRewardAmount(address rewardToken_, uint256 rewardAmount_) (abstract)

• Description:

  • Abstract method for adding new reward tokens. Child contract overrides this to add whitelisting checks or additional logic.

  • The base logic is available in _notifyRewardAmount(...) (see below).

10. _getReward(address owner_, address[] calldata rewardTokens_) (internal)

• Description:

  • The internal function that loops over rewardTokens_, calculates earned(...), updates s_lastRewardClaimByOwnerAndToken, and transfers the reward to owner_.

  • Finally, emits

11. _notifyRewardAmount(address sender_, address rewardToken_, uint256 rewardAmount_) (internal)

• Description:

  • Transfers rewardAmount_ of rewardToken_ from sender_ to this distributor.

  • Adds the difference in the contract’s balance to s_rewardAmountByTokenAndEpoch[rewardToken_][currentEpochStart]

Functions in IncentiveRewardsDistributor

Constructor

• Description:

  • Calls the RewardsDistributor constructor to set ESCROW_VOTE_MANAGER and ESCROW_MANAGER.

  • No additional logic besides inheritance.

getReward(address owner_, address[] calldata rewardTokens_)

• Description:

  • Implementation of getReward from both RewardsDistributor (abstract) and IIncentiveRewardsDistributor.

  • Allows the escrow vote manager to claim rewards for owner_.

notifyRewardAmount(address rewardToken_, uint256 rewardAmount_)

• Description:

  • Implementation of notifyRewardAmount from both RewardsDistributor (abstract) and IIncentiveRewardsDistributor.

  • First ensures rewardToken_ is whitelisted via

Events and Errors

Inherited Events

1. TokensDeposited(from, tokenId, amount)

2. TokensWithdrawn(from, tokenId, amount)

3. RewardNotified(from, token, epoch, amount)

Inherited Errors

• InvalidRewardToken()

• UnauthorizedAccess()

• ZeroAmountProvided()

No new custom events or errors are introduced in IncentiveRewardsDistributor beyond what’s inherited.

Summary

IncentiveRewardsDistributor leverages the robust, epoch-based reward accounting system from RewardsDistributor to facilitate secure incentive distribution in the CrossCurve ecosystem, adding token whitelisting checks and limiting reward claims (getReward) to calls from the escrow vote manager. This design ensures:

• Authorized Control: Only recognized and whitelisted tokens can be notified as rewards; only the escrow vote manager can trigger claims.

• Accurate Reward Calculations: Inherits deposit/withdraw logic to track each user’s epoch-based balance.

• Easy Integration: Conforms to the IIncentiveRewardsDistributor interface, providing consistent methods for reward notifications and claims across the system.

Together with the RewardsDistributor base contract, IncentiveRewardsDistributor offers a flexible, robust means of awarding incentive tokens in a multi-lock, epoch-based environment.