monomer

README

Monomer

Monomer uses the OP stack to make Cosmos applications deployable as Ethereum rollups.

⚠ Monomer is pre-production software and should be used with caution. ⚠

At a Glance

From the OP stack's perspective, Monomer replaces the default Ethereum compatible execution engine. From the Cosmos application's perspective, Monomer replaces the CometBFT consensus layer.

Development

We use Go 1.22. To run the e2e tests, you'll need the submodules and a configured L1 backend. We use buf to manage protobufs.

Prerequisites

1. Install go 1.22 or higher.

2. Initialize submodules:

   git submodule update --init --recursive
   

3. Install jq

4. Install foundry

5. Install buf:

   make install-buf
   

6. Install golangci-lint:

   make install-golangci-lint
   
   

7. Install go-test-coverage:

   make install-go-test-coverage
   
   

Running tests

1. Set up the environment for end-to-end (e2e) tests:

   make setup-e2e
   

2. Run the e2e tests:

   make e2e
   

3. Run the unit tests:

   make test
   

Code Quality, Linting and Coverage

1. Run linting:

   make lint
   

2. Check test coverage

   make check-cover
   

Cleaning Up

1. Clean up generated files and artifacts:

   make clean
   

Documentation

Index

• func AdaptCosmosTxsToEthTxs(cosmosTxs bfttypes.Txs) (ethtypes.Transactions, error)
• func AdaptNonDepositCosmosTxToEthTx(cosmosTx bfttypes.Tx) *ethtypes.Transaction
• func AdaptPayloadTxsToCosmosTxs(ethTxs []hexutil.Bytes) (bfttypes.Txs, error)
• func GetDepositTxs(txsBytes [][]byte) (ethtypes.Transactions, error)
• func NewChainConfig(chainID *big.Int) *params.ChainConfig
• func ValidForkchoiceUpdateResult(headBlockHash *common.Hash, id *engine.PayloadID) *opeth.ForkchoiceUpdatedResult
• type Application
• type Block
  • func MakeBlock(h *Header, txs bfttypes.Txs) (*Block, error)
  • func NewBlock(h *Header, txs bfttypes.Txs) *Block
  • func SetHeader(block *Block) (*Block, error)
  • func (b *Block) ToCometLikeBlock() *bfttypes.Block
  • func (b *Block) ToEth() (*ethtypes.Block, error)
• type ChainID
  • func (id ChainID) Big() *big.Int
  • func (id ChainID) HexBig() *hexutil.Big
  • func (id ChainID) String() string
• type CosmosETHAddress
  • func PubkeyToCosmosETHAddress(pubKey *ecdsa.PublicKey) CosmosETHAddress
  • func (a CosmosETHAddress) Encode(hrp string) (string, error)
• type Header
  • func (h *Header) ToComet() *bfttypes.Header
  • func (h *Header) ToEth() *ethtypes.Header
• type PayloadAttributes
  • func (p *PayloadAttributes) ID() *engine.PayloadID

Functions

func AdaptCosmosTxsToEthTxs

func AdaptCosmosTxsToEthTxs(cosmosTxs bfttypes.Txs) (ethtypes.Transactions, error)

func AdaptNonDepositCosmosTxToEthTx

func AdaptNonDepositCosmosTxToEthTx(cosmosTx bfttypes.Tx) *ethtypes.Transaction

func AdaptPayloadTxsToCosmosTxs

func AdaptPayloadTxsToCosmosTxs(ethTxs []hexutil.Bytes) (bfttypes.Txs, error)

AdaptPayloadTxsToCosmosTxs assumes the deposit transactions come first.

func GetDepositTxs

func GetDepositTxs(txsBytes [][]byte) (ethtypes.Transactions, error)

func NewChainConfig

func NewChainConfig(chainID *big.Int) *params.ChainConfig

func ValidForkchoiceUpdateResult

func ValidForkchoiceUpdateResult(headBlockHash *common.Hash, id *engine.PayloadID) *opeth.ForkchoiceUpdatedResult

ValidForkchoiceUpdateResult returns a valid ForkchoiceUpdateResult with given head block hash.

Types

type Application

type Application interface {
	Info(context.Context, *abcitypes.RequestInfo) (*abcitypes.ResponseInfo, error)
	Query(context.Context, *abcitypes.RequestQuery) (*abcitypes.ResponseQuery, error)

	CheckTx(context.Context, *abcitypes.RequestCheckTx) (*abcitypes.ResponseCheckTx, error)

	InitChain(context.Context, *abcitypes.RequestInitChain) (*abcitypes.ResponseInitChain, error)
	FinalizeBlock(context.Context, *abcitypes.RequestFinalizeBlock) (*abcitypes.ResponseFinalizeBlock, error)
	Commit(context.Context, *abcitypes.RequestCommit) (*abcitypes.ResponseCommit, error)

	RollbackToHeight(context.Context, uint64) error
}

type Block

type Block struct {
	Header *Header
	Txs    bfttypes.Txs
}

func MakeBlock

func MakeBlock(h *Header, txs bfttypes.Txs) (*Block, error)

MakeBlock creates a block and calculates the extrinsic properties on the header (like the block hash).

func NewBlock

func NewBlock(h *Header, txs bfttypes.Txs) *Block

NewBlock creates a new block. The header and txs must be non-nil. It performs no other validation.

func SetHeader

func SetHeader(block *Block) (*Block, error)

SetHeader calculates the extrinsic properties on the header (like the block hash) and resets them. It assumes the block has been created with NewBlock.

func (*Block) ToCometLikeBlock

func (b *Block) ToCometLikeBlock() *bfttypes.Block

func (*Block) ToEth

func (b *Block) ToEth() (*ethtypes.Block, error)

type ChainID

type ChainID uint64

func (ChainID) Big

func (id ChainID) Big() *big.Int

func (ChainID) HexBig

func (id ChainID) HexBig() *hexutil.Big

func (ChainID) String

func (id ChainID) String() string

type CosmosETHAddress

type CosmosETHAddress common.Address

CosmosETHAddress is a Cosmos address packed into an Ethereum address. Only addresses derived from secp256k1 keys can be packed into an Ethereum address. See [ADR-28] for more details.

func PubkeyToCosmosETHAddress

func PubkeyToCosmosETHAddress(pubKey *ecdsa.PublicKey) CosmosETHAddress

PubkeyToCosmosETHAddress converts a secp256k1 public key to a CosmosETHAddress. Passing in a non-secp256k1 key results in undefined behavior.

func (CosmosETHAddress) Encode

func (a CosmosETHAddress) Encode(hrp string) (string, error)

type Header

type Header struct {
	ChainID    ChainID
	Height     uint64
	Time       uint64
	ParentHash common.Hash
	StateRoot  common.Hash
	GasLimit   uint64
	Hash       common.Hash
}

func (*Header) ToComet

func (h *Header) ToComet() *bfttypes.Header

func (*Header) ToEth

func (h *Header) ToEth() *ethtypes.Header

ToEth converts a partial Monomer Header to an Ethereum Header. Extrinsic properties on the header (like the block hash) need to be set separately by SetHeader.

type PayloadAttributes

type PayloadAttributes struct {
	Timestamp             uint64
	PrevRandao            [32]byte
	SuggestedFeeRecipient common.Address
	Withdrawals           *ethtypes.Withdrawals
	NoTxPool              bool
	GasLimit              uint64
	ParentBeaconBlockRoot *common.Hash
	ParentHash            common.Hash
	Height                int64
	CosmosTxs             bfttypes.Txs
	// contains filtered or unexported fields
}

func (*PayloadAttributes) ID

func (p *PayloadAttributes) ID() *engine.PayloadID

ID returns a PaylodID (a hash) from a PayloadAttributes when it's applied to a head block. Hashing does not conform to go-ethereum/miner/payload_building.go PayloadID is only calculated once, and cached for future calls.