CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-eth-optimism--contracts

Smart contracts for Optimism Layer 2 scaling solution including L1/L2 messaging, bridging, rollup management, and predeploy contracts

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

l1-rollup-management.mddocs/

Layer 1 Rollup Management

L1 contracts responsible for managing the Optimistic Rollup infrastructure, including transaction ordering, state commitments, storage management, fraud proof verification, and deployment coordination.

CanonicalTransactionChain

Contract Path: L1/rollup/CanonicalTransactionChain.sol

Maintains the canonical ordering of L2 transactions and provides the authoritative transaction log for the Optimistic Rollup.

Constructor

constructor(
  address _libAddressManager,
  uint256 _maxTransactionGasLimit,
  uint256 _l2GasDiscountDivisor,
  uint256 _enqueueGasCost
);

Parameters:

  • _libAddressManager (address): Address manager contract
  • _maxTransactionGasLimit (uint256): Maximum gas limit per transaction
  • _l2GasDiscountDivisor (uint256): Divisor for L2 gas discount calculation
  • _enqueueGasCost (uint256): Gas cost for the enqueue function

Constants

uint256 public constant MIN_ROLLUP_TX_GAS = 100000;
uint256 public constant MAX_ROLLUP_TX_SIZE = 50000;

Key Functions

contract CanonicalTransactionChain {
  function enqueue(
    address _target,
    uint256 _gasLimit,
    bytes memory _data
  ) external;
  
  function appendQueueBatch(uint256 _numQueuedTransactions) external;
  
  function appendSequencerBatch() external;
  
  function getTotalElements() external view returns (uint256);
  function getTotalBatches() external view returns (uint256);
  
  function getQueueElement(uint256 _index) external view returns (
    bytes32 transactionHash,
    uint256 timestamp,
    uint256 blockNumber
  );
}

enqueue

Adds a transaction to the queue for inclusion in L2. Anyone can call this to force inclusion of a transaction.

Parameters:

  • _target (address): Target contract address on L2
  • _gasLimit (uint256): Gas limit for the transaction (must be >= MIN_ROLLUP_TX_GAS)
  • _data (bytes): Transaction data to execute

Usage:

// Force inclusion of a transaction in L2
ctc.enqueue(
  l2ContractAddress,
  200000,
  abi.encodeWithSignature("myFunction(uint256)", 123)
);

appendQueueBatch

Appends a batch of queued transactions to the chain (sequencer only).

Parameters:

  • _numQueuedTransactions (uint256): Number of queued transactions to include

appendSequencerBatch

Appends a batch of sequencer transactions to the chain (sequencer only).

Events

event TransactionEnqueued(
  address indexed _l1TxOrigin,
  address indexed _target,
  uint256 _gasLimit,
  bytes _data,
  uint256 indexed _queueIndex,
  uint256 _timestamp
);

event QueueBatchAppended(
  uint256 _startingQueueIndex,
  uint256 _numQueueElements,
  uint256 _totalElements
);

event SequencerBatchAppended(
  uint256 _startingQueueIndex,
  uint256 _numQueueElements,
  uint256 _totalElements
);

StateCommitmentChain

Contract Path: L1/rollup/StateCommitmentChain.sol

Manages state root commitments for L2 blocks and provides fraud proof verification.

Key Functions

contract StateCommitmentChain {
  function appendStateBatch(
    bytes32[] memory _batch,
    uint256 _shouldStartAtElement
  ) external;
  
  function deleteStateBatch(ChainBatchHeader memory _batchHeader) external;
  
  function verifyStateCommitment(
    bytes32 _element,
    ChainBatchHeader memory _batchHeader,
    ChainInclusionProof memory _proof
  ) external view returns (bool);
  
  function getTotalElements() external view returns (uint256);
  function getTotalBatches() external view returns (uint256);
  
  function getLastSequencerTimestamp() external view returns (uint256);
}

appendStateBatch

Appends a batch of state roots to the chain (sequencer only).

Parameters:

  • _batch (bytes32[]): Array of state roots to append
  • _shouldStartAtElement (uint256): Expected starting element index

Usage:

bytes32[] memory stateRoots = new bytes32[](10);
// ... populate state roots
scc.appendStateBatch(stateRoots, currentIndex);

deleteStateBatch

Deletes an invalid state batch during fraud proof process.

Parameters:

  • _batchHeader (ChainBatchHeader): Header of the batch to delete

verifyStateCommitment

Verifies that a state root is included in a committed batch.

Parameters:

  • _element (bytes32): State root to verify
  • _batchHeader (ChainBatchHeader): Batch header containing the element
  • _proof (ChainInclusionProof): Merkle proof of inclusion

Returns: bool - True if the commitment is valid

Events

event StateBatchAppended(
  uint256 indexed _batchIndex,
  bytes32 _batchRoot,
  uint256 _batchSize,
  uint256 _prevTotalElements,
  bytes _extraData
);

event StateBatchDeleted(
  uint256 indexed _batchIndex,
  bytes32 _batchRoot
);

ChainStorageContainer

Contract Path: L1/rollup/ChainStorageContainer.sol

Manages append-only storage for chain data with access control and metadata.

Key Functions

contract ChainStorageContainer {
  function setGlobalMetadata(bytes27 _globalMetadata) external;
  function getGlobalMetadata() external view returns (bytes27);
  
  function length() external view returns (uint256);
  
  function push(bytes32 _object) external;
  function push(bytes32 _object, bytes27 _globalMetadata) external;
  
  function get(uint256 _index) external view returns (bytes32);
  function deleteElementsAfterInclusive(uint256 _index) external;
}

setGlobalMetadata

Sets global metadata for the container (self only).

Parameters:

  • _globalMetadata (bytes27): Metadata to store

push

Adds a new element to the container (self only).

Parameters:

  • _object (bytes32): Element to add
  • _globalMetadata (bytes27, optional): Metadata for this push

get

Retrieves an element by index.

Parameters:

  • _index (uint256): Index of element to retrieve

Returns: bytes32 - The stored element

Events

event ObjectStored(
  bytes32 _object,
  uint256 _index
);

BondManager

Contract Path: L1/verification/BondManager.sol

Manages bonding for the fraud proof system, handling bond deposits, withdrawals, and slashing.

Key Functions

contract BondManager {
  function isCollateralized(address _who) external view returns (bool);
  
  function startBondWithdrawal(
    bytes32 _preStateRoot,
    bytes32 _postStateRoot
  ) external;
  
  function finalizeWithdrawal() external;
  
  function claim(address _who) external;
  
  function deposit() external payable;
  
  function getGasSpent(
    bytes32 _preStateRoot,
    bytes32 _postStateRoot
  ) external view returns (uint256);
}

isCollateralized

Checks if an address has sufficient bond collateral.

Parameters:

  • _who (address): Address to check

Returns: bool - True if sufficiently collateralized

startBondWithdrawal

Initiates the bond withdrawal process.

Parameters:

  • _preStateRoot (bytes32): State root before the disputed transition
  • _postStateRoot (bytes32): State root after the disputed transition

finalizeWithdrawal

Completes bond withdrawal after the dispute period.

claim

Claims another user's bond after a successful fraud proof.

Parameters:

  • _who (address): Address whose bond to claim

deposit

Deposits ETH as bond collateral.

Usage:

// Deposit bond
bondManager.deposit{value: bondAmount}();

// Check if collateralized
require(bondManager.isCollateralized(proposer), "Insufficient bond");

AddressDictator

Contract Path: L1/deployment/AddressDictator.sol

Manages atomic address updates during system upgrades with ownership transfer mechanisms.

Key Functions

contract AddressDictator {
  function setAddresses(
    string[] memory _names,
    address[] memory _addresses
  ) external;
  
  function transferAddressManagerOwnership(address _newOwner) external;
  
  function finalizeNamedAddressSet(
    string memory _name,
    address _namedAddress
  ) external;
}

setAddresses

Sets multiple addresses atomically.

Parameters:

  • _names (string[]): Array of address names
  • _addresses (address[]): Array of corresponding addresses

transferAddressManagerOwnership

Transfers ownership of the address manager.

Parameters:

  • _newOwner (address): New owner address

ChugSplashDictator

Contract Path: L1/deployment/ChugSplashDictator.sol

Manages ChugSplash proxy deployment and upgrade coordination.

Key Functions

contract ChugSplashDictator {
  function doActions(uint256 _step) external;
  
  function finalize() external;
  
  function isFinalized() external view returns (bool);
}

doActions

Executes a step in the deployment process.

Parameters:

  • _step (uint256): Step number to execute

finalize

Finalizes the deployment process.

Common Types

ChainBatchHeader

struct ChainBatchHeader {
  uint256 batchIndex;
  bytes32 batchRoot;
  uint256 batchSize;
  uint256 prevTotalElements;
  bytes extraData;
}

ChainInclusionProof

struct ChainInclusionProof {
  uint256 index;
  bytes32[] siblings;
}

Usage Examples

Transaction Enqueuing

contract L1Gateway {
  ICanonicalTransactionChain public ctc;
  
  function forceL2Transaction(
    address target,
    bytes calldata data
  ) external payable {
    // Calculate required gas
    uint256 gasLimit = gasleft() / 10; // Simplified calculation
    
    // Enqueue transaction for forced inclusion
    ctc.enqueue(target, gasLimit, data);
  }
}

State Verification

contract FraudProofVerifier {
  IStateCommitmentChain public scc;
  
  function verifyStateTransition(
    bytes32 stateRoot,
    ChainBatchHeader memory batchHeader,
    ChainInclusionProof memory proof
  ) public view returns (bool) {
    return scc.verifyStateCommitment(stateRoot, batchHeader, proof);
  }
}

Bond Management

contract ProposerContract {
  IBondManager public bondManager;
  
  modifier onlyCollateralized() {
    require(
      bondManager.isCollateralized(msg.sender),
      "Insufficient collateral"
    );
    _;
  }
  
  function proposeStateRoot(bytes32 stateRoot) external onlyCollateralized {
    // Propose new state root
    // ...
  }
  
  function depositBond() external payable {
    bondManager.deposit{value: msg.value}();
  }
}

docs

index.md

l1-messaging-bridging.md

l1-rollup-management.md

l2-messaging-bridging.md

l2-system-contracts.md

standards-interfaces.md

typescript-utilities.md

utility-libraries.md

tile.json