Predeployed Contracts - Cosmos Documentation

New to predeployed contracts? Start here:

Predeployed Contracts Concept - Understanding predeployed contracts and how they differ from precompiles
Predeployed Contracts Overview - Quick reference of available contracts
Building Your Chain Guide - Quick start configuration examples

Individual Contract Documentation:

Create2 Factory - Deterministic deployment patterns
Multicall3 - Batch operations examples
Permit2 - Signature-based approvals
Safe Factory - Multisig wallet deployment

Getting Started

There are several methods to deploy preinstalled contracts on a Cosmos EVM chain:

1. Genesis Configuration

The most straightforward method for new chains or testnets. Contracts are deployed when the chain is first initialized.

Default Configuration
Custom Genesis Configuration

If using the reference evmd application, your chain automatically includes default preinstalls, however they will not be active by default.

// Source: evmd/genesis.go:28-34
func NewEVMGenesisState() *evmtypes.GenesisState {
    evmGenState := evmtypes.DefaultGenesisState()
    evmGenState.Params.ActiveStaticPrecompiles = evmtypes.AvailableStaticPrecompiles
    evmGenState.Preinstalls = evmtypes.DefaultPreinstalls  // Defined in x/vm/types/preinstall.go
    return evmGenState
}

Local Development

The local_node.sh script automatically configures default preinstalls:

./local_node.sh
# Automatically deploys all default preinstalls

2. Governance Proposal

For chains already in production, use the MsgRegisterPreinstalls governance proposal:

Proposal Structure

The authority field must be set to the governance module account address, which is typically derived from the gov module name. This is usually something like cosmos10d07y265gmmuvt4z0w9aw880jnsr700j6zn9kn for the standard gov module.

{
  "messages": [
    {
      "@type": "/cosmos.evm.vm.v1.MsgRegisterPreinstalls",
      "authority": "[gov module account address]",
      "preinstalls": [
        {
          "name": "Multicall3",
          "address": "0xcA11bde05977b3631167028862bE2a173976CA11",
          "code": "0x6080604052..."
        }
      ]
    }
  ],
  "metadata": "ipfs://CID",
  "deposit": "10000000stake",
  "title": "Deploy Multicall3 Contract",
  "summary": "Deploy the Multicall3 contract to enable batched calls"
}

Submission Process

# Submit proposal
evmd tx gov submit-proposal proposal.json \
  --from mykey \
  --chain-id cosmosevm_9001-1 \
  --gas auto

# Vote on proposal
evmd tx gov vote 1 yes --from mykey

3. Chain Upgrade Handler

Include predeployed contracts as part of a coordinated chain upgrade:

func CreateUpgradeHandler(
    mm *module.Manager,
    configurator module.Configurator,
    evmKeeper *evmkeeper.Keeper,
) upgradetypes.UpgradeHandler {
    return func(ctx sdk.Context, plan upgradetypes.Plan, fromVM module.VersionMap) (module.VersionMap, error) {
        // Add preinstalls during upgrade
        if err := evmKeeper.AddPreinstalls(ctx, evmtypes.DefaultPreinstalls); err != nil {
            return nil, err
        }

        return mm.RunMigrations(ctx, configurator, fromVM)
    }
}

Implementation Details

Validation Process

All preinstall deployments undergo strict validation:

Address Validation
- Must be valid Ethereum address format (40 hex characters)
- Cannot conflict with existing contracts
- Should not overlap with precompile reserved addresses (typically 0x1-0x9FF)
Code Validation
- Must be valid EVM bytecode (hex encoded)
- Cannot have empty code hash
- Must pass bytecode verification
Conflict Prevention
- Checks for existing contracts at target address
- Validates against account keeper for existing accounts
- Ensures no code hash conflicts with different bytecode

Storage and State

Predeployed contracts are stored in the chain state like regular contracts:

// Actual deployment process from x/vm/keeper/preinstalls.go
func (k *Keeper) AddPreinstalls(ctx sdk.Context, preinstalls []types.Preinstall) error {
    for _, preinstall := range preinstalls {
        address := common.HexToAddress(preinstall.Address)
        accAddress := sdk.AccAddress(address.Bytes())

        if len(preinstall.Code) == 0 {
            return errorsmod.Wrapf(types.ErrInvalidPreinstall,
                "preinstall %s has no code", preinstall.Address)
        }

        codeHash := crypto.Keccak256Hash(common.FromHex(preinstall.Code)).Bytes()
        if types.IsEmptyCodeHash(codeHash) {
            return errorsmod.Wrapf(types.ErrInvalidPreinstall,
                "preinstall %s has empty code hash", preinstall.Address)
        }

        // Check for existing code hash conflicts
        existingCodeHash := k.GetCodeHash(ctx, address)
        if !types.IsEmptyCodeHash(existingCodeHash.Bytes()) &&
           !bytes.Equal(existingCodeHash.Bytes(), codeHash) {
            return errorsmod.Wrapf(types.ErrInvalidPreinstall,
                "preinstall %s already has a different code hash", preinstall.Address)
        }

        // Check that the account is not already set
        if acc := k.accountKeeper.GetAccount(ctx, accAddress); acc != nil {
            return errorsmod.Wrapf(types.ErrInvalidPreinstall,
                "preinstall %s already has an account in account keeper", preinstall.Address)
        }

        // Create account and store code
        account := k.accountKeeper.NewAccountWithAddress(ctx, accAddress)
        k.accountKeeper.SetAccount(ctx, account)
        k.SetCodeHash(ctx, address.Bytes(), codeHash)
        k.SetCode(ctx, codeHash, common.FromHex(preinstall.Code))
    }
    return nil
}

Verification and Testing

Verify Deployment

After deployment, verify contracts are properly installed:

# Query contract code via CLI
evmd query evm code 0x4e59b44847b379578588920ca78fbf26c0b4956c

# Check account exists
evmd query evm account 0x4e59b44847b379578588920ca78fbf26c0b4956c

// Verify via Web3
const code = await provider.getCode("0x4e59b44847b379578588920ca78fbf26c0b4956c");
console.log("Deployed:", code !== "0x");

Testing Strategy

Local Testing: Deploy on local node first
Testnet Validation: Test governance proposal process
Integration Testing: Verify interactions with other contracts
Gas Analysis: Monitor gas consumption patterns
Security Audit: Review bytecode before mainnet deployment

Best Practices

Security Considerations

Bytecode Verification: Always verify that bytecode matches official releases
Address Selection: Ensure addresses don’t conflict with future plans
Audit Requirements: Even well-known contracts should be reviewed
Immutability: Remember that predeployed contracts cannot be upgraded

Deployment Recommendations

Start with Defaults: Use evmtypes.DefaultPreinstalls unless you have specific requirements
Test Thoroughly: Validate on testnet before mainnet deployment
Document Changes: Clearly communicate any non-standard deployments to developers
Monitor Usage: Track contract interactions to understand adoption

Common Pitfalls to Avoid

Don’t deploy to addresses that could conflict with precompiles (typically 0x1-0x9FF)
Don’t assume contracts are deployed - always check first
Don’t modify standard contract addresses without strong justification
Don’t deploy untested or unaudited bytecode

Known Issues

Critical - Safe Factory Bytecode ErrorThe Safe Singleton Factory bytecode in DefaultPreinstalls (x/vm/types/preinstall.go:30-32) is identical to the Create2 factory bytecode, which is incorrect and will not function for deploying Safe wallets.Verification:

# Create2 bytecode
0x7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe03601600081602082378035828234f58015156039578182fd5b8082525050506014600cf3

# Safe Factory bytecode (INCORRECT - same as Create2)
0x7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe03601600081602082378035828234f58015156039578182fd5b8082525050506014600cf3

Before deploying to production:

Get the correct Safe Singleton Factory bytecode from the official repository
Update your genesis preinstalls configuration with the correct bytecode
Test thoroughly on a testnet
See the Safe Factory documentation for more details

Temporary workaround: If you need Safe functionality immediately, manually update the bytecode in your genesis.json or use a governance proposal to deploy the correct contract.

Adding Custom Preinstalls

To add custom contracts beyond the defaults:

// Define custom preinstall
customPreinstall := types.Preinstall{
    Name:    "MyCustomContract",
    Address: "0xYourChosenAddress",
    Code:    "0xCompiledBytecode",
}

// Validate before deployment
if err := customPreinstall.Validate(); err != nil {
    return err
}

// Add via appropriate method (genesis, governance, or upgrade)
preinstalls := append(evmtypes.DefaultPreinstalls, customPreinstall)

Troubleshooting

Common Issues

Issue	Cause	Solution
”preinstall already has an account in account keeper”	Address collision	Choose different address
”preinstall has empty code hash”	Invalid or empty bytecode	Verify bytecode hex string is valid
”preinstall address is not a valid hex address”	Malformed address	Ensure 0x prefix and 40 hex chars
”invalid authority”	Wrong governance address	Use correct gov module account address
Contract not found after deployment	Wrong network	Verify chain ID and RPC endpoint

Debugging Steps

Check chain genesis configuration
Verify proposal passed and executed
Query contract code directly
Test with simple contract interaction
Review chain logs for errors

Quick Reference

Default Preinstalls

| Contract | Address | Bytecode Field | Status | |-|||—| | Create2 | 0x4e59b44847b379578588920ca78fbf26c0b4956c | preinstall.Code | ✓ Verified | | Multicall3 | 0xcA11bde05977b3631167028862bE2a173976CA11 | preinstall.Code | ✓ Verified | | Permit2 | 0x000000000022D473030F116dDEE9F6B43aC78BA3 | preinstall.Code | ✓ Verified | | Safe Factory | 0x914d7Fec6aaC8cd542e72Bca78B30650d45643d7 | preinstall.Code | ⚠️ Bytecode Issue | | EIP-2935 | 0x0b | params.HistoryStorageCode | ✓ System Contract | Source: x/vm/types/preinstall.go:13-39

Genesis Configuration Paths

{
  "app_state": {
    "vm": {
      "preinstalls": [...],  // Configure predeployed contracts
      "params": {
        "active_static_precompiles": [...]  // Configure precompiles (different!)
      }
    }
  }
}

Further Resources

Official Specifications

EIP-1014: CREATE2 Specification - Understanding deterministic deployment
EIP-2935: Historical Block Hashes - Block hash storage specification

Contract Documentation

Multicall3 Documentation - Official Multicall3 repository
Permit2 Introduction - Uniswap’s Permit2 design
Safe Contracts - Safe multisig implementation

Cosmos EVM Resources

VM Module Reference - Complete VM module configuration

Cosmos EVM

​Getting Started

​1. Genesis Configuration

​Local Development

​2. Governance Proposal

​Proposal Structure

​Submission Process

​3. Chain Upgrade Handler

​Implementation Details

​Validation Process

​Storage and State

​Verification and Testing

​Verify Deployment

​Testing Strategy

​Best Practices

​Security Considerations

​Deployment Recommendations

​Common Pitfalls to Avoid

​Known Issues

​Adding Custom Preinstalls

​Troubleshooting

​Common Issues

​Debugging Steps

​Quick Reference

​Default Preinstalls

​Genesis Configuration Paths

​Further Resources

​Official Specifications

​Contract Documentation

​Cosmos EVM Resources

Getting Started

1. Genesis Configuration

Local Development

2. Governance Proposal

Proposal Structure

Submission Process

3. Chain Upgrade Handler

Implementation Details

Validation Process

Storage and State

Verification and Testing

Verify Deployment

Testing Strategy

Best Practices

Security Considerations

Deployment Recommendations

Common Pitfalls to Avoid

Known Issues

Adding Custom Preinstalls

Troubleshooting

Common Issues

Debugging Steps

Quick Reference

Default Preinstalls

Genesis Configuration Paths

Further Resources

Official Specifications

Contract Documentation

Cosmos EVM Resources