Theseus Hardfork: Guidelines for Developers and Users

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.sol contract.
• 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.

Action: Download and upgrade your node to the latest release v1.0.16 for Core Testnet2 and v1.0.17 for Core Mainnet.

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_estimateGas for 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-multiplier to 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 --legacy flag 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_estimateGas and increase where needed
• Us-- -gas-estimate-multiplier to 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.