Technical Design Brief: Arbitrum Features for Local EVM Devnets

interface PrecompileHandler {
  address: string;
  version: string;
  handleCall(
    calldata: Buffer,
    context: ExecutionContext
  ): Promise<PrecompileResult>;
  getConfig(): PrecompileConfig;
}

interface PrecompileRegistry {
  register(handler: PrecompileHandler): void;
  getHandler(address: string): PrecompileHandler | null;
  listHandlers(): PrecompileHandler[];
}

interface ExecutionContext {
  blockNumber: number;
  chainId: number;
  gasPrice: bigint;
  caller: string;
  callStack: string[];
  l1Context?: L1Context;
}

interface PrecompileResult {
  success: boolean;
  data?: Buffer;
  gasUsed: number;
  error?: string;
}

interface PrecompileConfig {
  chainId: number;
  arbOSVersion: number;
  l1BaseFee: bigint;
  gasPriceComponents: GasPriceComponents;
}

// Extend Hardhat's transaction processing pipeline
class DepositTransactionProcessor {
  parseTransaction(rawTx: Buffer): DepositTransaction | null;
  validateTransaction(tx: DepositTransaction): ValidationResult;
  executeTransaction(
    tx: DepositTransaction,
    context: ExecutionContext
  ): ExecutionResult;
}

// Hook into Hardhat's EVM
hardhatNetwork.evm.transactionProcessor.registerType(
  0x7e,
  new DepositTransactionProcessor()
);

// Extend revm transaction types
#[derive(Debug, Clone)]
pub enum TransactionType {
    Legacy,
    Eip2930,
    Eip1559,
    Deposit(DepositTransaction), // New: 0x7e
}

// Transaction parsing extension
impl Transaction {
    pub fn decode_deposit(data: &[u8]) -> Result<Self, Error> {
        if data[0] != 0x7e {
            return Err(Error::InvalidTransactionType);
        }
        // Parse deposit transaction fields
        let decoded: Vec<Vec<u8>> = rlp::decode_list(&data[1..])?;
        // ... field parsing
    }
}

interface ArbitrumConfig {
  chainId: number; // Default: 42161 (Arbitrum One)
  arbOSVersion: number; // Default: 20
  l1: {
    baseFee: bigint; // Default: 20 gwei
    gasPriceEstimate: bigint; // Default: 25 gwei
    feeModel: "static" | "dynamic"; // Default: 'static'
  };
  precompiles: {
    arbSys: { enabled: boolean; address: string };
    arbGasInfo: { enabled: boolean; address: string };
  };
  transactions: {
    depositType: { enabled: boolean; gasLimit: number };
  };
}

class ArbSysHandler implements PrecompileHandler {
  address = "0x0000000000000000000000000000000000000064";
  version = "1.0.0";

  async handleCall(
    calldata: Buffer,
    context: ExecutionContext
  ): Promise<PrecompileResult> {
    const selector = calldata.slice(0, 4);

    switch (selector.toString("hex")) {
      case "a3b1b31d": // arbChainID()
        return this.arbChainID(context);
      case "051038f2": // arbBlockNumber()
        return this.arbBlockNumber(context);
      case "4d2301cc": // arbBlockHash(uint256)
        return this.arbBlockHash(calldata, context);
      case "4d2301cc": // arbOSVersion()
        return this.arbOSVersion(context);
      default:
        return { success: false, gasUsed: 0, error: "Unknown selector" };
    }
  }

  private arbChainID(context: ExecutionContext): PrecompileResult {
    return {
      success: true,
      data: ethers.utils.defaultAbiCoder.encode(["uint256"], [context.chainId]),
      gasUsed: 3,
    };
  }

  private arbBlockNumber(context: ExecutionContext): PrecompileResult {
    return {
      success: true,
      data: ethers.utils.defaultAbiCoder.encode(
        ["uint256"],
        [context.blockNumber]
      ),
      gasUsed: 3,
    };
  }
}

class ArbGasInfoHandler implements PrecompileHandler {
  address = "0x000000000000000000000000000000000000006C";
  version = "1.0.0";

  async handleCall(
    calldata: Buffer,
    context: ExecutionContext
  ): Promise<PrecompileResult> {
    const selector = calldata.slice(0, 4);

    switch (selector.toString("hex")) {
      case "4d2301cc": // getPricesInWei()
        return this.getPricesInWei(context);
      case "4d2301cc": // getL1BaseFeeEstimate()
        return this.getL1BaseFeeEstimate(context);
      case "4d2301cc": // getCurrentTxL1GasFees()
        return this.getCurrentTxL1GasFees(context);
      default:
        return { success: false, gasUsed: 0, error: "Unknown selector" };
    }
  }

  private getPricesInWei(context: ExecutionContext): PrecompileResult {
    const config = this.getConfig();
    const l2BaseFee = context.gasPrice;
    const l1BaseFee = config.l1.baseFee;
    const l1GasPrice = config.l1.gasPriceEstimate;

    return {
      success: true,
      data: ethers.utils.defaultAbiCoder.encode(
        ["uint256", "uint256", "uint256", "uint256", "uint256"],
        [l2BaseFee, l1BaseFee, 0, l2BaseFee, 0] // 5-tuple: L2 cost, L1 calldata, storage, base L2, congestion
      ),
      gasUsed: 10,
    };
  }
}

interface DepositTransaction {
  type: 0x7e;
  sourceHash: string; // bytes32 - Unique deposit identifier
  from: string; // address - L1 sender (aliased if contract)
  to: string; // address - L2 recipient (or null for contract creation)
  mint: bigint; // uint256 - ETH value to mint on L2
  value: bigint; // uint256 - ETH value to transfer
  gasLimit: number; // uint64 - Gas limit for execution
  isCreation: boolean; // bool - Whether this creates a contract
  data: string; // bytes - Call data
}

class DepositTransactionExecutor {
  async execute(
    tx: DepositTransaction,
    context: ExecutionContext
  ): Promise<ExecutionResult> {
    // 1. Validate transaction structure
    const validation = this.validateTransaction(tx);
    if (!validation.valid) {
      return { success: false, error: validation.error };
    }

    // 2. Resolve L1→L2 address aliasing
    const resolvedFrom = await this.resolveL1Address(tx.from, context);

    // 3. Mint ETH if specified
    if (tx.mint > 0) {
      await this.mintETH(resolvedFrom, tx.mint);
    }

    // 4. Execute transaction with proper context
    const executionContext = {
      ...context,
      caller: resolvedFrom,
      value: tx.value,
      gasLimit: tx.gasLimit,
    };

    // 5. Forward to standard transaction execution
    return await this.forwardToEVM(tx, executionContext);
  }
}

class ArbitrumErrorHandler {
  handlePrecompileError(error: PrecompileError, context: ErrorContext): string {
    const suggestions = this.getSuggestions(error, context);

    return `
  Arbitrum Precompile Error: ${error.message}
  Address: ${error.address}
  Selector: ${error.selector}
  Suggestion: ${suggestions}
 Docs: https://docs.arbitrum.io/precompiles
    `.trim();
  }

  private getSuggestions(
    error: PrecompileError,
    context: ErrorContext
  ): string {
    switch (error.type) {
      case "UNSUPPORTED_METHOD":
        return "This method is not yet implemented in the local emulator. Consider using a supported alternative or deploy to Arbitrum testnet.";
      case "INVALID_PARAMETERS":
        return "Check parameter types and ranges. Refer to Arbitrum documentation for expected formats.";
      case "STATE_UNAVAILABLE":
        return "Required state is not available in local environment. Configure mock values or use testnet.";
      default:
        return "Check configuration and ensure Arbitrum features are enabled.";
    }
  }
}

describe("ArbSys Handler", () => {
  let handler: ArbSysHandler;
  let context: ExecutionContext;

  beforeEach(() => {
    handler = new ArbSysHandler();
    context = createMockContext();
  });

  it("should return correct chain ID", async () => {
    const result = await handler.handleCall(
      ethers.utils.hexlify(ethers.utils.id("arbChainID()").slice(0, 4)),
      context
    );

    expect(result.success).to.be.true;
    expect(
      ethers.utils.defaultAbiCoder.decode(["uint256"], result.data)[0]
    ).to.equal(42161);
  });
});

describe("Arbitrum One Compatibility", () => {
  it("should match mainnet arbChainID()", async () => {
    // Local emulator
    const localResult = await localArbSys.arbChainID();

    // Arbitrum One RPC
    const mainnetResult = await arbitrumOneProvider.call({
      to: "0x0000000000000000000000000000000000000064",
      data: ethers.utils.id("arbChainID()"),
    });

    expect(localResult).to.equal(mainnetResult);
  });
});