The Theseus Hardfork is a major protocol upgrade scheduled to activate on the Core blockchain. The hardfork will be activated on Core Testnet2 on May 30, 2025 at 08:00 AM UTC and on Core Mainnet on June 25, 2025 at 08:00 AM UTC. This upgrade brings powerful new infrastructure capabilities, including real-time tracing, protocol-level fee distribution, and critical upstream merges from BNB Smart Chain (BSC).
This guide outlines what developers and users need to know to prepare for Theseus and ensure a seamless transition.
Background: What is the Theseus Hardfork?
Theseus hardfork incorporates changes that improve Core’s developer tooling and incentive mechanisms by introducing a new revenue sharing protocol-level framework and live on-chain tracing. While enhancing transparency and modularity, the upgrade requires all validators and full node operators to upgrade their node software. It encourages developers to adapt to the new tooling and revenue-sharing logic where applicable.
Key Features of the Theseus Hardfork
1. Core’s Protocol-Level Fee Sharing
Allows developers, DAOs, and stablecoin issuers to earn a pre-configured share of transaction gas fees.
Configurable by governance via the
Configuration.solcontract.Enables flexible, event-triggered revenue streams tied to smart contract usage.
Designed to boost stablecoin adoption and network activity
No changes required in contract logic; the reward mechanism executes after EVM execution
Fully compatible with existing EVM contracts once configured
2. Live Chain Tracing with Hooks
Enables native real-time tracing of on-chain transactions and contract events.
Designed for improved observability, debugging, and analytics.
Requires no third-party indexing or tracing tools.
3. BSC v1.4.10 Merge
Integrates protocol improvements and optimizations from BNB Smart Chain version 1.4.10. Enhances EVM compatibility and performance.
Changes Affecting Developers and Users
1. Mandatory Node Upgrade
All validators and full node operators on the Core blockchain must upgrade to the latest releases before the scheduled deadlines. For Core Testnet2 update to v1.0.16 by May 30, 2025, at 08:00 AM UTC. For Core Mainnet, update to v1.0.17 by June 25, 2025, at 08:00 AM UTC.
If a validator or full node fails to upgrade before the hardfork, it will become incompatible with the upgraded network. As a result, the node will not be able to sync with peers, process transactions, or participate in consensus. This can result in operational downtime and network disconnection. Upgrading on time is essential to maintain uninterrupted service and ensure continued participation in the Core blockchain.
2. Developer Workflow Considerations
2.1 Live Tracing Support: No configuration needed to use tracing; developers can integrate hooks with monitoring tools to receive live on-chain event data.
2.2 Core’s Protocol-Level Fee Sharing Impact on Gas
There are no breaking changes for most wallets or dApps.
Apps using
eth_estimateGasfor transactions will continue to work as expected.⚠️ Caution: For dApps/wallets with hardcoded gas values (common in frameworks like Foundry, Hardhat, or Brownie), the devs will need to increase gas limits when interacting with contracts enabled for Core’s new incentive mechanism.
If using Foundry, use
--gas-estimate-multiplierto increase the estimated gas limit. For scripts interacting with contracts configured for protocol-level incentives through this upgrade, a higher multiplier (200-500) may be needed.Always use
--legacyflag as Core uses legacy transactions.Test thoroughly with different gas values to ensure transaction success.
Note: At the time of the hardfork, no contracts will be configured for this upgrade, so most apps will not be immediately affected.
Testing on Core Testnet2 is encouraged if you're building with custom gas logic or preparing for the integration of this upgrade. It is highly recommended to thoroughly test your dapps and smart contracts on Core Testnet2 before redeployment to Core Mainnet.
2.3 Enabling Protocol-Level Contract-Based Fee Sharing
To participate in protocol-level fee sharing:
Submit a proposal for your smart contract via Core governance
Include the contract address, triggering events, gas values, and reward splits
Upon approval, gas-based rewards are automatically distributed upon event execution
3. User-Level Impact
For general users and wallet holders, no action is required. Transactions may incur slightly higher gas costs if interacting with contracts configured for protocol-level revenue sharing.
Testing & Compatibility
Developers should begin testing their contracts now, especially those with:
Custom gas logic
Gas-sensitive on-chain workflows
The new protocol-level revenue sharing will not affect contracts unless explicitly registered
What Happens If Developers Don’t Upgrade or Test?
While the Theseus hardfork introduces no breaking changes for existing contracts, failing to adapt can result in:
Missed opportunities to earn via incentives from transaction activities
Inaccurate gas handling if not accounting for the new revenue sharing distributions
Poor dApp performance under live tracing or gas-sensitive conditions
Action Items for Developers
Upgrade local/dev/test infrastructure to v1.0.16 and mainnet infrastructure to v1.0.17
Submit configuration proposals for contracts to enable protocol-level revenue sharing via governance upon hardfork activation
Test gas usage with
eth_estimateGasand increase where neededUs
-- -gas-estimate-multiplierto increase the estimated gas limit in case of using hardcoded gas values or frameworks like Foundry, Hardhat, or Brownie.Use Core Testnet2 to validate revenue sharing distributions and live event tracing
Update documentation and notify users of any gas changes if the new revenue sharing framework is adopted
Conclusion
The Theseus Hardfork is a foundational upgrade that enhances developer tooling, aligns incentives, and improves the Core developer experience. With native tracing, new revenue models, and upgrades to geth, developers and validators alike are encouraged to take full advantage of the features included in the Theseus hard fork.
For questions or support, visit the Core Dev Forum or join the official Core Discord.