Implement bitmap-encoded effect addresses for gas-efficient step checking #52
+2,079
−281
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Rust CLI tool that mines salts for Effect contract addresses where the most significant 9 bits encode the EffectStep bitmap. This enables gas savings by replacing shouldRunAtStep() external calls with address bitmap checks. Features: - CREATE3 address computation matching CreateX at 0xba5Ed099633D3B313e4D5F7bdc1305d3c28ba5Ed - 9-bit bitmap extraction from address MSB - Parallel mining with rayon - Config generation for all 24 effects - Single effect and batch mining modes https://claude.ai/code/session_01CniUcnBFuUAwhJkwn9S3oi
…checks - Add EffectBitmap.sol library with NUM_EFFECT_STEPS constant for future extensibility - Replace 4 shouldRunAtStep() external calls in Engine.sol with bitmap checks - Update effect-miner to use NUM_EFFECT_STEPS constant - Generalize comments to not hardcode 9 steps The bitmap is encoded in the most significant N bits of effect addresses, where N is the number of EffectSteps. This eliminates external calls during effect execution, saving gas. https://claude.ai/code/session_01CniUcnBFuUAwhJkwn9S3oi
- Add EffectDeployer.sol library for deploying effects via CreateX - Add DeployEffectsCreate3.s.sol script template for deploying all core effects - Includes bitmap verification on deployment - Documents required salts and how to mine them https://claude.ai/code/session_01CniUcnBFuUAwhJkwn9S3oi
- Add EffectSalts struct and deployGameFundamentalsCreate3() to EngineAndPeriphery.s.sol - Add EffectTestHelper.sol for deploying effects with correct bitmaps in tests - Tests can use vm.etch to place effect bytecode at addresses with correct bitmaps The existing deployGameFundamentals() is preserved for backward compatibility. Use deployGameFundamentalsCreate3() with pre-mined salts for production deployments. https://claude.ai/code/session_01CniUcnBFuUAwhJkwn9S3oi
- Updated EffectTestHelper to auto-compute bitmaps from effect's shouldRunAtStep - Added deployWithCorrectBitmap() which queries the effect and builds bitmap automatically - Updated all test files to use the new generalized helper instead of hardcoded bitmaps - All 182 tests now pass with the new bitmap-based effect checking https://claude.ai/code/session_01CniUcnBFuUAwhJkwn9S3oi
Effects are now deployed with deployWithCorrectBitmap() so that their addresses have the correct EffectStep bitmap in the MSB. This ensures the gas measurements accurately reflect the bitmap-based checks in Engine.sol rather than the old external shouldRunAtStep calls. Gas savings observed (production-representative measurements): - B1_Execute: 40% reduction - FirstBattle: 42% reduction https://claude.ai/code/session_01CniUcnBFuUAwhJkwn9S3oi
Replace heavy alloy-primitives crate with plain byte arrays: - Address = [u8; 20] - B256 = [u8; 32] This reduces dependencies from 189 to 48 packages and Cargo.lock from 44KB to 11KB (75% reduction). The miner only needs keccak256 hashing and basic byte manipulation, not the full Ethereum type system. https://claude.ai/code/session_01CniUcnBFuUAwhJkwn9S3oi
Pass a pre-populated EffectContext struct containing battleKey, active mon indices, playerSwitchForTurnFlag, and turnId to all effect hooks. This eliminates the need for effects to call ENGINE.battleKeyForWrite() and other getters, saving ~2600 gas per avoided external call. Gas savings observed: - Battle execution: 78-88k gas saved per battle (~2.4-2.9%) - Execute with effects: 13.5k gas saved (~1.4-1.8%) Changes: - Added EffectContext struct to Structs.sol - Updated IEffect interface with new hook signatures - Updated Engine.sol to create and pass context - Updated all 38 effect implementations (src/ and test/) https://claude.ai/code/session_01CniUcnBFuUAwhJkwn9S3oi
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This PR introduces a gas-efficient mechanism for checking which EffectSteps an effect should run at by encoding this information directly in the effect's contract address. Instead of calling
effect.shouldRunAtStep(), the Engine now reads the bitmap from the address's most significant bits, eliminating external calls and reducing gas costs.Key Changes
EffectBitmap Library (
src/lib/EffectBitmap.sol): New library that extracts and validates EffectStep bitmaps from contract addresses. The top 9 bits of an address encode which of the 9 EffectSteps the effect runs at.EffectDeployer Library (
src/lib/EffectDeployer.sol): Helper library for deploying effects via CREATE3 with pre-mined salts that produce addresses with correct bitmaps. Includes verification to ensure deployed addresses have the expected bitmap.Engine.sol Updates: Replaced all
effect.shouldRunAtStep()calls withEffectBitmap.shouldRunAtStep(address(effect), step)for gas efficiency. This eliminates external calls during battle execution.Deployment Scripts:
DeployEffectsCreate3.s.sol: Standalone script for deploying effects via CREATE3 with bitmap-encoded addressesEngineAndPeriphery.s.sol: AddeddeployGameFundamentalsCreate3()function and EffectSalts struct for CREATE3 deploymentTest Infrastructure (
test/abstract/EffectTestHelper.sol): New helper contract that allows tests to deploy effects at addresses with correct bitmaps usingvm.etch. This enables testing the bitmap-based step checking without requiring pre-mined salts.Test Updates: Updated all test files to use
deployWithCorrectBitmap()helper when creating effects, ensuring tests work with the new bitmap-based system..gitignore: Added
tools/effect-miner/target/for Rust build artifacts.Implementation Details
effect-minerCLI tool (referenced in comments) is used to generate these saltsMigration Path
new Effect()patternhttps://claude.ai/code/session_01CniUcnBFuUAwhJkwn9S3oi