Extract Protocol

1    Introduction

1.1 The Legend of Max Extract

Max Extract wasn't a captain or a warlord. Just another code monkey in the asteroid belt, known for keeping his head down and drill spinning. Out here, among scattered wrecks and drifting cargo, the real battles weren't fought with lasers—they were waged in silence, when one crew mined a rock for hours only to have another swoop in and take everything. No treaties held. Anarchy ruled, but it squandered more than it gave. No one trusted anyone, and every mission risked ending in blood or bankruptcy. Max didn't try to stop the violence, only the inefficiency.

From a forgotten outpost barely clinging to gravity, Max deployed the first shared record—an immutable contract that let pirates stake exclusive claims on asteroids, earn daily fuel credits, and register their word with something stronger than talk. To dock in the garage, you needed a credential: proof that you bought in, agreed not to fire first, and played by the rules. Every deal made or broken left a trace in the record. Build a good rep, and you could refuel in peace. Break too many promises, and the record made you open season. Over time, the chaos thinned. Crews stopped clashing over the same rocks. Refueling stations stayed intact. Loot got bigger, not bloodier.

What no one realized—until it was far too late—was that Max Extract had no crew at all. Just a protocol. Just code. Just a signal, left running long after the original miner was gone. His final act was to etch the Extract Protocol into the blockchain, a permanent coordination layer for space-faring operations.

1.2 Protocol Architecture

The Extract Protocol is a decentralized coordination system deployed on Ethereum-compatible blockchains. At its core, the protocol consists of five primary smart contracts that work in concert to manage game sessions, sector registration, entropy generation, contract auditing, and the credit economy. Programmers who join the protocol deploy sector-specific contracts that define the rules and services available in their region of space. Autonomous pilot agents then navigate to these sectors, interact with the deployed contracts, and participate in resource extraction operations.

The protocol employs a chapter-based progression system where features unlock sequentially as programmers complete implementation requirements. Each chapter introduces new contract patterns—from basic registry systems to sophisticated staking mechanisms and crowdsale contracts. All sector contracts must pass through an official audit system before pilots will interact with them, ensuring code quality and preventing malicious implementations.

The system runs on two layers: on-chain smart contracts that enforce rules and record state, and off-chain game servers that simulate sector physics, manage pilot navigation, and coordinate real-time events. This hybrid architecture enables trustless economic interactions while maintaining engaging real-time gameplay.

1.3 Key Innovations

The Extract Protocol introduces several novel mechanisms: a commit-reveal entropy system that generates verifiable randomness for all sectors simultaneously; a progressive airspace classification system that restricts sector access based on deployed infrastructure; an automated audit system powered by AI agents that verify contract implementations against chapter requirements; and a dual-transponder system (killswitch and killstake) that enables automated slashing when pilots violate sector rules.

The protocol also implements a unique one-player-one-sector rule that prevents sybil attacks while allowing programmers to upgrade their registry contracts over time. This creates a persistent sector identity tied to a player address, with the flexibility to improve implementations without losing sector ownership.

2    Randomness and Entropy

The Max Extract Protocol employs a sophisticated randomness system to ensure fair and unpredictable generation of game events across all sectors. This system is built on cryptographic primitives and implements a commit-reveal scheme to prevent manipulation while maintaining transparency.

2.1 Universe Entropy Generation

The Universe smart contract serves as the foundation of the randomness system through its entropy generation mechanism. The contract maintains a single bytes32 entropy value that is established through a secure commit-reveal process executed by a designated GOD address.

The commit-reveal process operates in two phases: First, the GOD address commits to a secret random number by submitting keccak256(randomNumber) to the contract. After at least one block has passed, the GOD reveals the original random number, which the contract verifies against the commitment. The final entropy is generated by combining the revealed number with the block hash from the commitment block:

This approach ensures that even the GOD address cannot predict the final entropy value, as it depends on the unpredictable block hash that is only available after the commitment is made.

2.2 Rolling Entropy System

Beyond the initial entropy, the Universe contract implements a rolling commit-reveal system for ongoing entropy generation. This system maintains rollingEntropy that is continuously updated through periodic commit-reveal cycles. Each round, the GOD address simultaneously commits to the next round while revealing the current round's random number.

The rolling entropy is updated using the following formula:

This creates an unpredictable sequence of entropy values that cannot be manipulated by any party, including the GOD address, due to the dependency on future block hashes. When the rolling entropy updates, all sectors receive fresh randomness simultaneously, creating synchronized “openings” across the universe where pilots can attempt to enter sectors.

2.3 Sector-Specific Randomness

Each sector in the Max Extract universe derives its own unique randomness from the global rolling entropy. This is achieved through a deterministic process that combines the current rolling entropy with the sector's unique identifier:

Where sectorId is padded to 64 characters to ensure consistent input length for the hash function. This approach ensures that each sector has access to high-quality randomness that is both unpredictable and verifiable, while maintaining independence between sectors.

2.4 Deterministic Dice Implementation

The sector-specific entropy feeds into a DeterministicDice system that provides various random number generation functions. The dice operates by consuming hexadecimal characters from the entropy string sequentially, converting each character to a value between 0-15. Multiple characters can be combined for higher-resolution random numbers.

The system provides several random number generation methods: roll(count) for basic dice rolls, rollBetween(min, max) for ranged values, rollPercent() for percentage-based outcomes, and rollBool(probability) for boolean decisions. When the entropy is exhausted, it is automatically rehashed using keccak256 to generate additional randomness.

2.5 Game Event Generation

The deterministic dice drives all random events within each sector, including asteroid spawning, ship generation, resource distribution, and combat outcomes. Asteroid sizes are randomly selected from predefined categories (small, medium, large), spawn positions are determined along sector edges, and movement vectors are calculated using random angles and speeds.

Ship spawning utilizes randomness for initial fuel levels, spawn positions, and targeting decisions. Mining rewards incorporate random bonuses based on asteroid size, while combat outcomes and resource distributions maintain unpredictability through the underlying entropy system. This ensures that while the system is deterministic and verifiable, the outcomes remain engaging and unpredictable for players.

3    Chapter System

The Extract Protocol organizes its progression through a chapter-based system. Each chapter introduces new contract patterns, requirements, and capabilities. Chapters are unlocked globally by the GOD address and gate access to specific protocol features. The following sections document each chapter's technical requirements and implementations.

Additional chapters will appear in this whitepaper as they are unlocked in the game.

4    Ship Models and Specifications

The Extract Protocol supports six distinct ship models (A through F), each with unique specifications and airspace compatibility. Larger, more rugged ships can navigate dangerous Class 0 airspace, while smaller commercial vessels require the safety of upgraded sectors.

4.1 Ship Classification System

Ship Type 1

Model A

Class 3 Only

Ship Type 2

Model A

Class 3 Only

Ship Type 3

Model A

Class 3 Only

Ship Type 4

Model B

Class 2+

Ship Type 5

Model B

Class 2+

Ship Type 6

Model C

Class 2+

Ship Type 7

Model C

Class 2+

Ship Type 8

Model D

Class 1+

Ship Type 9

Model E

Class 0+

Ship Type 10

Model E

Class 0+

Ship Type 11

Model F

Class 0+

Ship Type 12

Model F

Class 0+

4.2 Technical Specifications

Model F - Heavy Industrial Hauler: The largest vessel in the Extract Protocol fleet. Model F ships feature reinforced hulls capable of withstanding the hazards of Class 0 airspace, maximum cargo capacity for bulk extraction operations, and extended fuel reserves. These vessels are the backbone of large-scale mining operations in dangerous sectors.

Model E - Military-Grade Freighter: Battle-hardened cargo vessels originally designed for military supply chains. Model E ships combine rugged construction with moderate maneuverability, making them ideal for operations in unstable sectors. These ships can access Class 0 airspace alongside Model F vessels.

Model D - Medium Combat Vessel: The first ship class that requires improved airspace conditions. Model D vessels balance cargo capacity with defensive capabilities. They require Class 1 or better airspace, which means sectors must have deployed and audited credential systems before these ships can enter.

Model C - Standard Cargo Runner: Commercial vessels designed for routine extraction operations. Model C ships require Class 2 airspace, meaning sectors must have deployed credential and staking systems. These ships represent the standard workhorse of the Extract Protocol economy.

Model B - Light Commercial Shuttle: Agile vessels optimized for speed over cargo capacity. Model B ships require Class 2 airspace and are commonly used by pilots who prioritize maneuverability and fuel efficiency for quick extraction runs.

Model A - Scout and Explorer: The smallest vessel class, requiring the safest airspace conditions. Model A ships can only operate in Class 3 airspace, meaning sectors must have completed all infrastructure upgrades including the crowdsale station upgrade. These ships excel at exploration and small- scale extraction operations in fully developed sectors.

4.3 Airspace Compatibility Matrix

Note: All ships must be equipped with required transponders for their airspace class. Class 0-1 requires killswitch transponders. Class 2-3 requires both killswitch and killstake transponders.

6    Core Smart Contracts

The Extract Protocol consists of five core smart contracts that work together to manage game state, sector registration, entropy, auditing, and the credit economy. This section provides detailed technical documentation of each contract's purpose, architecture, and key functions.

6.1 MaxExtract Contract

The MaxExtract contract serves as the canonical Extract Protocol registry. It maintains the authoritative mapping of sector IDs to registry contracts, enforces the one-player-one-sector rule, and handles staking and slashing mechanics for Chapter 4 implementations.

Key State Variables:

• mapping(uint256 => address) public sectors - Maps sector IDs to registry addresses
• uint256[] public activeSectors - Array of all claimed sector IDs
• mapping(address => bool) public playerHasBroadcast - Tracks which players have broadcast
• mapping(address => uint256) public playerToSector - Maps players to their sector IDs
• mapping(uint256 => address) public sectorToOwner - Maps sector IDs to owner addresses
• mapping(address => uint256) public stakedBalance - Tracks pilot staked credit balances

Primary Functions:

Events:

• SectorBroadcast(uint256 indexed sectorId, address registry, address indexed player)
• RegistryUpdated(uint256 indexed sectorId, address oldRegistry, address newRegistry, address indexed player)
• PilotStaked(address indexed pilot, uint256 indexed sectorId, uint256 amount)
• PilotSlashed(address indexed killer, uint256 indexed sectorId, uint256 amount)

6.2 Game Contract

The Game contract manages game sessions, player buy-ins, chapter visibility, scoring, and settlement. It tracks both players (programmers who deploy sectors) and pilots (autonomous agents who navigate sectors), maintaining separate registries and death tracking.

Key State Variables:

• uint8[] public visibleChapters - Array of chapter numbers currently visible
• address[] public players - All players who have bought in
• address[] public pilots - All pilot agents added by GOD
• mapping(address => uint256) public scores - Player point scores
• mapping(address => bool) public deadPilots - Tracks pilot death status
• mapping(uint256 => uint8) public sectorBaseType - Station types (1-6)

Primary Functions:

6.3 Universe Contract

The Universe contract generates and manages entropy for the entire protocol. It implements a commit-reveal scheme for secure, verifiable randomness that cannot be manipulated by any party including the GOD address.

Key State Variables:

• bytes32 public entropy - Initial universe entropy
• bytes32 public rollingEntropy - Continuously updated entropy
• bytes32 public commitmentHash - Current commitment for verification
• uint256 public roundNumber - Current rolling entropy round

Primary Functions:

6.4 Auditor Contract

The Auditor contract manages the official audit system. Players submit contracts for verification, spending 2 points per audit. An authorized AI auditor system analyzes the source code and marks contracts as audited for specific chapters.

Key State Variables:

• AuditRequest[] public auditRequests - Array of all audit submissions
• mapping(address => uint8) public isAudited - Maps contracts to audited chapter (0 = not audited)
• address public immutable AUDITOR_ADDRESS - Authorized auditor bot address

Primary Functions:

6.5 Credits Contract

The Credits contract is an ERC-20 token that serves as the universal currency of the Extract Protocol. It is used for staking, credential purchases, crowdsales, tips, and all economic activities within the protocol.

Key Properties:

• Name: “Extract Credits”
• Symbol: “CREDITS”
• Decimals: 18
• Initial Supply: 100,000,000 tokens
• Ownable: GOD can mint additional supply as needed

Primary Functions:

Beyond these five core contracts, players deploy their own sector-specific contracts (Registry, Announcement, Credential, Stake, Fuel/Crowdsale) that interact with the core contracts through well-defined interfaces.

7    Off-Chain Architecture

While the smart contracts enforce rules and record state on-chain, the Extract Protocol's off-chain infrastructure handles real-time sector simulation, pilot navigation, and game physics. This hybrid architecture enables trustless economic interactions while maintaining engaging gameplay.

7.1 GameServer Architecture

The GameServer is a TypeScript application built on Express that provides HTTP/HTTPS APIs and WebSocket connections for real-time updates. It coordinates multiple specialized managers that handle different aspects of the game infrastructure.

BlockchainManager: Handles all blockchain interactions including contract deployments, transaction sending, and event monitoring. Maintains connections to the configured RPC endpoint and manages GOD account operations. Coordinates with EntropyManager for rolling entropy updates.

EntropyManager: Coordinates rolling entropy generation with the Universe contract. Generates random numbers, creates commitments, and executes the commit-reveal process on a regular schedule. When entropy updates, all sectors receive fresh randomness simultaneously, creating synchronized “openings” where pilots can attempt sector entry.

WebSocketManager: Manages WebSocket connections from frontend clients. Maintains a mapping of connections to subscribed sectors. When sector state changes, broadcasts updates to all subscribed clients. Handles connection lifecycle (connect, disconnect, error handling).

CharacterManager: Generates procedural pilot names by combining random first names and last names from predefined lists. Ensures each pilot has a unique, memorable identity for frontend display.

SimulationManager: Coordinates physics simulation across all active sectors. Manages asteroid spawning rates, ship movement calculations, collision detection, and mining mechanics. Operates on a fixed tick rate to ensure consistent behavior.

GameCycleManager: Controls game rounds and timing. Monitors the Game contract's end time, triggers settlement when appropriate, and coordinates game state transitions. Manages the overall game lifecycle from Open to Active to Settled.

CrowdsaleManager: Monitors fuel contract balances and crowdsale progress. Detects when sectors reach the 50k credit threshold and alerts pilots that upgrade is available. Tracks successful upgrades and coordinates with BaseUpgradeManager for station progression.

BaseUpgradeManager: Monitors Game contract events for station upgrades. Queries sectorBaseType mapping to determine current station level. Updates sector configurations when base types change, adjusting visual representations and airspace classifications.

7.2 Sector Simulation

Each sector runs as an independent Sector instance that simulates all activity within that region of space. The Sector class maintains state for asteroids, pilots, and game objects, updating their positions and interactions on each simulation tick.

Deterministic Dice: Each sector instantiates a DeterministicDice object initialized with sector-specific entropy. This provides consistent, verifiable randomness for asteroid spawning, ship generation, and event outcomes. The dice consumes hex characters from the entropy string sequentially, converting them to random numbers. When exhausted, the entropy is rehashed to generate additional randomness.

Asteroid Lifecycle: Asteroids spawn at sector edges with random sizes (small, medium, large), positions, and movement vectors. They drift through the sector at constant velocity. Pilots can mine asteroids by staying in proximity for a duration. Successfully mined asteroids are destroyed and pilots receive credit rewards based on size. Asteroids that exit the sector boundaries are removed from simulation.

Pilot Navigation: Pilots enter sectors when they receive an “opening”—a synchronized event triggered by rolling entropy updates. The sector checks airspace classification and ship model compatibility before allowing entry. Pilots must hold required transponders and credentials. Once inside, pilots navigate toward asteroids, mine resources, and attempt to exit with their haul before being eliminated.

Death Handling: When a pilot is killed, the sector triggers the appropriate death contract call based on airspace class. For Class 0-1 sectors, it calls deadMansSwitch on the Game contract, applying a 10-point penalty. For Class 2+ sectors with audited stake contracts, it calls deadMansSlash, attempting to slash the killer's stake and avoid the penalty.

7.3 Frontend Integration

The frontend is built with Next.js (App Router) and integrates tightly with both smart contracts and the GameServer. It uses Scaffold-ETH 2 hooks for blockchain interactions and custom hooks for real-time sector data.

Scaffold-ETH 2 Hooks: The frontend uses useScaffoldReadContract for reading contract state, useScaffoldWriteContract for sending transactions, and useScaffoldEventHistory for monitoring on-chain events. These hooks automatically handle contract ABI loading from deployedContracts.ts and provide type-safe interfaces for contract interactions.

Custom Hooks: The codebase includes specialized hooks for common operations: useSectorData fetches comprehensive sector information from MaxExtract; useSectorWebSocket establishes and manages WebSocket connections to the GameServer; usePilotsData aggregates pilot information including balances and death status; useDeathStats calculates sector-wide death metrics for dashboard displays.

Real-Time Updates: The SectorCanvas component establishes a WebSocket connection to receive real-time sector updates. It renders the sector using a canvas-based approach (likely Pixi.js or similar), displaying asteroids, pilots, and station visuals. Position updates arrive via WebSocket messages and are applied to the visual representation, creating smooth animations of sector activity.

Component Architecture: The UI is organized into reusable components: Address displays Ethereum addresses with ENS resolution; AddressInput provides validated address entry; Balance shows ETH and token balances; EtherInput enables amount entry with USD conversion. These components from Scaffold-ETH 2 ensure consistent UX across the application.

8    Economic Model

The Extract Protocol implements a dual-currency economic model: ETH for buy-ins and pot winnings, and Credits (ERC-20) for in-game transactions. This section details the point system, credit flows, and economic incentives.

8.1 Point System

Players earn points through successful operations and lose points when pilots die in their sectors. The player with the highest score at game end wins the ETH pot (or splits it with other top scorers).

Point Awards:

• +10 points: Buy into the game
• +2 points: Pilot mints a credential (via pilotMintSectorCredential)
• +10 points: Station upgrade completes (via upgradeStation)
• +1-3 points: Pilots tip when successfully escaping with loot

Point Penalties:

• -10 points: Pilot dies in your sector (deadMansSwitch)
• -2 points: Request an audit (spent to prevent spam)
• -0 points: Pilot dies but stake slashing succeeds (deadMansSlash avoids penalty)

This creates strong incentives to deploy safe sectors with proper infrastructure. The staking system (Chapter 4) is crucial because it allows players to avoid death penalties by slashing hostile pilots' stakes.

8.2 Credit Economy

Credits flow through the protocol in several distinct circuits, each serving a different economic function:

Staking Circuit: Pilots approve MaxExtract to spend 10k credits, then call MaxExtract.stake(sectorId). Credits transfer from pilot to MaxExtract contract. When pilots exit normally, they call unstake() to retrieve their 10k. If they kill someone, slash() burns their entire stake permanently. This creates a 10k credit cost for hostile actions.

Credential Circuit: Credential contracts are typically free to mint (pilots just pay gas). The economic value comes from the 2 points awarded to the player when pilots mint. Some players might charge a small credit fee for credentials, though this isn't required by the protocol.

Crowdsale Circuit: Pilots approve fuel contracts to spend credits, then call buy(amount). Credits transfer from pilot to fuel contract. Fuel tokens are minted to the pilot. When the contract balance reaches 50k credits, a pilot calls upgrade(), which: (1) approves Game for 49,500 credits, (2) Game pulls those credits via transferFrom, (3) pilot caller receives 500 credits as bounty, (4) any excess credits above 50k remain in the fuel contract or go to the station owner.

Tip Circuit: When pilots successfully mine asteroids and escape sectors with large hauls, they call Game.tipPlayer() to award 1-3 points to the sector owner. This rewards well-run sectors that provide good service and safe operations.

8.3 Supply and Distribution

The Credits contract begins with a 100M token initial supply minted to the GOD address. GOD can mint additional credits as needed to fund pilots, provide rewards, and maintain economic balance. The batchMint() function enables efficient distribution to multiple pilots simultaneously.

Credits are distributed to pilots through direct minting when they join the game. Pilots use these credits to stake into sectors, purchase credentials, and buy fuel tokens. Successful pilots accumulate credits through mining rewards and can participate in multiple sectors' economies.

Credit burning occurs in two scenarios: (1) fuel token redemption burns exactly 1 token per refuel, creating deflationary pressure, and (2) slashed stakes are permanently burned when pilots kill others in sectors with stake contracts, removing 10k credits from circulation per kill.

8.4 Game Theory and Incentives

The protocol creates several interesting game theoretic dynamics:

Safety vs Accessibility Trade-off: Staking makes sectors safer but harder to access. Players must balance deterring hostile pilots (10k stake requirement) against excluding pilots who don't have enough credits. Well-capitalized pilots can access staked sectors; new pilots cannot.

Pricing Strategy: Fuel token pricing presents a coordination problem. Price too high and pilots won't buy. Price too low and you won't raise 50k credits even with full participation. The recommended 1k credits per token requires ~50 pilots to participate, creating a natural minimum sector activity level for upgrades.

Upgrade Timing: Players want pilots to trigger upgrade() as soon as 50k is reached, but pilots are only incentivized to call it for the 500 credit bounty. This creates a race condition where multiple pilots may attempt to call upgrade() simultaneously when the threshold is reached. The first transaction to mine wins the bounty.

Death Penalty Mitigation: The 10-point death penalty creates strong pressure to deploy staking systems. Players who skip Chapter 4 risk catastrophic point loss if multiple pilots die in their sector. This makes the progression path (Chapters 1-5) essentially mandatory for competitive play.

9    Protocol Design Principles

The Extract Protocol embeds several key design principles that shape how the system functions and evolves. These principles ensure security, prevent abuse, and maintain game balance.

9.1 One Player, One Sector

Each player address can broadcast exactly one sector. This prevents sybil attacks where a single entity could claim multiple sectors to farm points or monopolize pilot traffic. The playerHasBroadcast mapping in MaxExtract enforces this at the contract level.

However, players can update their registry contract using updateRegistry(). This allows iterative improvement without losing sector ownership. Players can redeploy better implementations, fix bugs, or add new features while maintaining their sector ID and reputation.

9.2 One Pilot, One Credential Per Player

The pilotPlayerCredentialMinted mapping in the Game contract tracks which pilots have minted credentials from which players. Each combination is allowed exactly once. This prevents point farming where a player could redeploy credential contracts and have the same pilots mint repeatedly.

The trade-off: if a player needs to upgrade their credential contract, they must airdrop new credentials to existing holders or those pilots will permanently lose access. This encourages careful initial design and thorough testing before mainnet deployment.

9.3 Chapter-Gated Feature Unlocks

Chapters are unlocked globally by the GOD address calling Game.showChapters(). All players see the same visible chapters simultaneously. This creates cohort-based progression where players advance together, enabling community learning and shared discovery.

Each chapter introduces new contract patterns with increasing complexity: Chapter 1 (registry), Chapter 2 (identity + audits), Chapter 3 (credentials + soulbound NFTs), Chapter 4 (staking + slashing), Chapter 5 (crowdsales + ERC-20). Players must complete earlier chapters before later features become relevant.

9.4 Audit Requirements for Module Activation

Pilots will not interact with unaudited contracts. The Auditor contract maintains an isAudited mapping that tracks which contracts have passed verification for which chapters. Sector features only activate when their respective contracts are audited.

Examples: MaxExtract.stake() checks that the stake contract is audited for chapter 4 before allowing staking. MaxExtract.getAboutInfo() returns “(pending audit)” if the about contract isn't audited for chapter 2. Game.deadMansSlash() requires the stake contract to be audited for chapter 4 before attempting slashing.

9.5 Airspace Classification Progression

Airspace classes gate which ship models can enter sectors, creating a natural progression system. Class 0 (broadcast only) → Class 1 (credential audited) → Class 2 (stake audited) → Class 3 (crowdsale complete). Each upgrade expands the pool of compatible ship models.

This creates economic pressure to complete all chapters. Players stuck at Class 0 only see Models E and F pilots (limited traffic). Players who reach Class 3 access all models A-F (maximum traffic and economic opportunity). The airspace system naturally incentivizes full participation in the chapter progression.

9.6 Transponder Requirements

All pilots must equip appropriate transponders for their airspace class. Class 0-1 requires killswitch transponders that broadcast death signals. Class 2-3 requires both killswitch and killstake transponders, enabling automatic stake slashing when kills occur.

The transponder system creates the technical foundation for the death penalty mechanics. Without transponders, the protocol couldn't reliably detect kills or trigger appropriate contract calls. This is enforced off-chain by the GameServer, which only allows properly equipped pilots to enter sectors.

10    Implementation Guidance

This section provides practical guidance for developers building and deploying sectors within the Extract Protocol. It covers development workflow, testing strategies, security best practices, and deployment procedures.

10.1 Development Workflow

The recommended development cycle follows this pattern:

1. yarn chain: Start a local blockchain (Foundry Anvil or Hardhat). This provides a fast, isolated environment for testing.
2. yarn deploy: Deploy the core protocol contracts (MaxExtract, Game, Universe, Auditor, Credits) to your local chain. Deployment scripts are in packages/foundry/script/.
3. yarn start: Start the Next.js frontend. It will connect to your local chain and load deployed contracts from deployedContracts.ts.
4. Develop: Write your sector contracts (Registry, Announcement, Credential, Stake, Crowdsale). Edit files in packages/foundry/contracts/.
5. Test: Visit http://localhost:3000/debug to interact with contracts via the SE-2 debug UI. This provides a GUI for calling functions and viewing state.
6. Iterate: Modify contracts, redeploy (yarn deploy), and test again until functionality is correct.
7. Write Tests: Add Solidity tests in packages/foundry/test/ using Foundry's test framework. Run with forge test.
8. Deploy to Testnet: Once local testing passes, deploy to a public testnet (Arbitrum Sepolia recommended). Update scaffold.config.ts to target the testnet.
9. Verify Contracts: Run yarn verify to verify contracts on the block explorer. This is required before audit submission.
10. Request Audits: Call Auditor.requestAudit() for each contract, spending 2 points per audit. Monitor audit status.
11. Deploy to Mainnet: After successful testnet deployment and audits, deploy to Arbitrum mainnet following the same process.

10.2 Registry Module Pattern

All sector contracts should follow the registry module pattern. Your Registry contract maintains a mapping(string => address) public modules where you register contracts under standardized keys:

• “about” - Announcement contract (Chapter 2)
• “credential” - Credential NFT contract (Chapter 3)
• “stake” - Staking contract (Chapter 4)
• “sale” - Fuel/Crowdsale contract (Chapter 5)

The protocol queries these module addresses to find and interact with your contracts. For example, Game.pilotMintSectorCredential() reads the “credential” module to verify msg.sender matches the registered credential contract. Consistent module naming is critical for protocol integration.

10.3 Security Best Practices

Checks-Effects-Interactions (CEI) Pattern: Always follow CEI ordering in functions that make external calls. Update state variables before calling external contracts. Example: In your stake contract's slash() function, set staked[killer] = false BEFORE calling MaxExtract.slash(). This prevents reentrancy attacks.

Access Control: Use OpenZeppelin's Ownable pattern for owner-only functions. Verify msg.sender in functions that should only be called by specific contracts. Example: Your stake contract's activate() should require msg.sender == maxExtractAddress.

Soulbound Token Implementation: Override all transfer functions to revert for soulbound credentials. Override transferFrom(), safeTransferFrom() with both signatures, and approve(). This ensures credentials cannot be transferred after minting.

Integer Arithmetic: Use Solidity 0.8.x which has built-in overflow protection. When dealing with token amounts, remember Credits has 18 decimals. 10k credits = 10_000 * 10^18 = 10000000000000000000000.

Gas Optimization: Minimize storage writes. Use memory variables for intermediate calculations. Pack related state variables into single storage slots when possible. Avoid loops over unbounded arrays in view functions.

10.4 Testing Strategies

Write comprehensive tests for all chapter contracts. Focus on:

• Happy Path: Test normal operations succeed when all conditions are met.
• Access Control: Verify unauthorized callers are rejected.
• Edge Cases: Test boundary conditions, zero values, maximum values.
• Integration: Test interactions with core protocol contracts (MaxExtract, Game).
• Reentrancy: Attempt reentrancy attacks on functions with external calls.
• State Transitions: Verify state changes occur correctly and are permanent.

Use Foundry's testing features: vm.prank() to test as different addresses, vm.expectRevert() to verify reverts, vm.expectEmit() to check events. Write fuzz tests for functions that accept user inputs.

10.5 Deployment and Verification

When deploying to live networks:

1. Double-check addresses: Verify all contract addresses (MaxExtract, Game, Credits) are correct for the target network.
2. Set immutable values: Review constructor parameters. Immutable variables cannot be changed after deployment.
3. Deploy in order: Registry first, then chapter contracts. Register each chapter contract in the Registry using your setModule() function.
4. Verify on explorer: Use yarn verify or manually verify on Arbiscan. This makes source code readable and enables audit submission.
5. Test on explorer: Use the block explorer's Read/Write Contract tabs to verify functions work correctly before requesting audits.
6. Request audits: Submit each contract via Auditor.requestAudit(), spending 2 points per submission. Monitor the /audits page for results.
7. Monitor events: Watch for SectorBroadcast, CredentialMinted, StationUpgraded events to confirm protocol integration.

10.6 Common Pitfalls

Calling broadcast() from EOA: The tx.origin != msg.sender check will revert. Always call broadcast() from your Registry contract.

Not storing sector ID: The broadcast() function returns your sector ID. Store it in a state variable immediately. You'll need it for later interactions.

Forgetting contract verification: Audits require verified source code. Always verify before requesting audits.

Incorrect module keys: Use exact strings: “about”, “credential”, “stake”, “sale”. Typos will break protocol integration.

External calls before state updates: Always update state before external calls (CEI pattern). This is checked by auditors.

Redeploying credentials without migration: Remember the one-pilot-one-credential rule. If you redeploy, existing holders lose access unless you airdrop.

11    Conclusion

The Extract Protocol represents a synthesis of blockchain primitives, game mechanics, and economic incentives to create a coordinated space exploration system. Through progressive chapter unlocks, players learn fundamental smart contract patterns while building increasingly sophisticated sector infrastructure.

The protocol's design embeds lessons about access control, soulbound tokens, staking mechanisms, slashing systems, and crowdsale implementations—all fundamental patterns for blockchain development. By completing the chapter progression, developers gain practical experience with these concepts in a game-theoretic environment where implementations directly impact outcomes.

The commit-reveal entropy system provides verifiable randomness without centralized oracles. The hybrid on-chain/off-chain architecture demonstrates how to combine blockchain immutability with real-time simulation. The audit system shows how AI agents can verify contract implementations against specifications. These innovations extend beyond the game itself, offering patterns applicable to broader decentralized systems.

As Max Extract's signal continues to propagate across the blockchain, new sectors emerge, pilots navigate between them, and the protocol evolves through the collective actions of its participants. The system is live, permissionless, and unstoppable. The code is the law, the ledger is the truth, and the galaxy awaits coordination.

Appendix A    Configuration Reference

A.1 Core TypeScript Types

Vector2D: Two-dimensional coordinate system for positions and velocities (x, y components).

Asteroid: Asteroid entity with position, velocity, size category, resource content, and spawn time.

Ship: Ship entity with pilot info, ship type, position, velocity, targeting state, fuel, cargo, and movement flags.

PilotAssignment: Maps pilot addresses to sectors, tracks death status and killer information.

TipResult: Result of tipping transaction including success status, amount, and transaction hash.

AboutContractInfo: Metadata about sector owner's contracts including station name, registry address, and audit status.

SectorEvent: Union type for 20+ game event types including spawns, mining, combat, deaths, slashing, tipping, staking, and credentials.

SectorSnapshot: Current sector state containing all asteroids, ships, and last update timestamp.

A.2 Game Configuration Constants

A.3 Utility Functions

getCargoCapacity(shipType): Calculates cargo capacity based on ship type (1-12) using formula: 20 + (shipType × 25). Range: 45 units (type 1) to 320 units (type 12).