EVM Blockchain Configuration

This guide covers the configuration options for running self-anchoring on EVM-compatible blockchains.

Anchor Contract

Self-anchoring requires an anchor contract deployed on your chosen EVM blockchain.

Pre-deployed Contracts

The anchor contract is already deployed on the following networks:

Network	Chain ID	Contract Address
Ethereum Mainnet	1	0x231055A0852D67C7107Ad0d0DFeab60278fE6AdC
Gnosis Chain	100	0x231055A0852D67C7107Ad0d0DFeab60278fE6AdC

You can use these addresses directly with --evm-contract-address without deploying your own contract.

Deploying to Other Networks

To deploy the anchor contract on a different EVM chain:

The contract source code is available at: ceramicnetwork/ceramic-anchor-service/contracts

The contract (CeramicAnchorServiceV2.sol) implements CIP-110 for indexable anchors.

Deployment steps:

1. Clone the repository:

   git clone https://github.com/ceramicnetwork/ceramic-anchor-service.git
   cd ceramic-anchor-service/contracts

2. Install dependencies (requires Foundry):

   make installDeps
   make build

3. Deploy to your network:

   export ETH_WALLET_PK=your-private-key
   export ETH_RPC_HOST=https://rpc.yournetwork.com
   export ETH_RPC_PORT=443
   make create

4. Note the deployed contract address from the output for use with --evm-contract-address.

Required Options

All of these options must be provided together to enable self-anchoring:

Option	Environment Variable	Description
--evm-rpc-url	CERAMIC_ONE_EVM_RPC_URL	RPC endpoint URL for submitting anchor transactions and verifying anchor proofs
--evm-private-key	CERAMIC_ONE_EVM_PRIVATE_KEY	Private key in hex format (without 0x prefix)
--evm-chain-id	CERAMIC_ONE_EVM_CHAIN_ID	Network/chain ID (e.g., 1 for Ethereum mainnet)
--evm-contract-address	CERAMIC_ONE_EVM_CONTRACT_ADDRESS	Deployed anchor contract address (see Deploying the Anchor Contract)

The --evm-rpc-url is used both for submitting anchor transactions and for verifying anchor proofs on that chain.

Optional Settings

Option	Environment Variable	Default	Description
--evm-confirmations	CERAMIC_ONE_EVM_CONFIRMATIONS	4	Number of block confirmations before anchor is final
--anchor-interval	CERAMIC_ONE_ANCHOR_INTERVAL	3600	Anchoring frequency in seconds
--additional-chain-rpc-urls	CERAMIC_ONE_ADDITIONAL_CHAIN_RPC_URLS	-	Comma-separated list of RPC URLs for validating anchors from other chains

Validating Anchors from Other Chains

If your node syncs events from the network that were anchored on different chains (e.g., historical anchors or events from other nodes), you can provide additional RPC endpoints to validate those proofs:

ceramic-one daemon \
  --evm-rpc-url https://rpc.gnosis.io \
  --additional-chain-rpc-urls https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY,https://polygon-rpc.com \
  ...

The node uses the first valid RPC for each chain ID.

Configuration Methods

CLI Flags

ceramic-one daemon \
  --evm-rpc-url https://rpc.yournetwork.com \
  --evm-private-key abcd1234... \
  --evm-chain-id 12345 \
  --evm-contract-address 0x1234567890abcdef... \
  --evm-confirmations 4 \
  --anchor-interval 3600

Environment Variables

export CERAMIC_ONE_EVM_RPC_URL=https://rpc.yournetwork.com
export CERAMIC_ONE_EVM_PRIVATE_KEY=abcd1234...
export CERAMIC_ONE_EVM_CHAIN_ID=12345
export CERAMIC_ONE_EVM_CONTRACT_ADDRESS=0x1234567890abcdef...
export CERAMIC_ONE_EVM_CONFIRMATIONS=4
export CERAMIC_ONE_ANCHOR_INTERVAL=3600

ceramic-one daemon

Docker Configuration

version: '3.8'

services:
  ceramic-one:
    image: public.ecr.aws/r5b3e0r5/3box/ceramic-one:latest
    network_mode: "host"
    environment:
      - CERAMIC_ONE_EVM_RPC_URL=https://rpc.yournetwork.com
      - CERAMIC_ONE_EVM_PRIVATE_KEY=${EVM_PRIVATE_KEY}
      - CERAMIC_ONE_EVM_CHAIN_ID=12345
      - CERAMIC_ONE_EVM_CONTRACT_ADDRESS=0x...
      - CERAMIC_ONE_EVM_CONFIRMATIONS=4
      - CERAMIC_ONE_ANCHOR_INTERVAL=3600
    volumes:
      - ceramic-one-data:/root/.ceramic-one

volumes:
  ceramic-one-data:
    driver: local

Security Considerations

Private Key Management

• Never commit private keys to version control
• Use environment variables or a secrets manager for production deployments
• Consider using a dedicated wallet with limited funds for anchoring
• Rotate keys periodically according to your security policies

RPC Endpoint Security

• Use HTTPS endpoints only
• Consider running your own RPC node for production workloads
• Be aware of rate limits on public RPC providers
• Monitor RPC endpoint availability

Wallet Funding

• Ensure the wallet has sufficient funds for transaction fees
• Set up monitoring and alerts for low balances
• Consider the transaction costs of your chosen network when planning

Configuration Tips

Choosing Confirmation Count

The --evm-confirmations setting determines how many blocks must be mined after your anchor transaction before it's considered final:

• Lower values (1-2): Faster finality, slightly higher reorganization risk
• Default (4): Good balance for most networks
• Higher values (6+): Maximum security, slower finality

Adjust based on your network's block time and finality guarantees.

Anchor Interval

The --anchor-interval controls how frequently anchoring occurs:

• Shorter intervals: More frequent anchoring, higher costs, faster timestamp verification
• Longer intervals: Lower costs, events wait longer for anchoring

Choose based on your application's requirements for timestamp verification speed versus cost.

Migration from Remote Anchor Service

If you were previously using the --remote-anchor-service-url option, this is now deprecated in favor of self-anchoring.

To migrate:

1. Remove the --remote-anchor-service-url configuration
2. Choose a network and use a pre-deployed contract or deploy your own
3. Ensure your wallet is funded on your chosen network
4. Add the EVM configuration options described above

Troubleshooting

Transaction Failures

If anchor transactions are failing:

• Verify the wallet has sufficient funds for gas fees
• Check that the RPC endpoint is accessible and responsive
• Confirm the chain ID matches the network your RPC endpoint connects to
• Ensure the contract address is correct for your network

Slow Anchoring

If anchoring is taking longer than expected:

• Check network congestion on your chosen blockchain
• Verify the RPC endpoint is performant
• Consider adjusting --anchor-interval for your use case

Connection Issues

If Ceramic One cannot connect to the RPC endpoint:

• Test the endpoint URL directly with curl or another HTTP client
• Check for firewall rules blocking outbound connections
• Verify the endpoint supports the required JSON-RPC methods

Transaction Recovery

Ceramic One automatically handles transaction recovery for pending anchor operations from previous runs. If the daemon is restarted while anchoring transactions are pending, it will:

1. Detect pending transactions from the previous session
2. Monitor their status on the blockchain
3. Complete the anchoring process once transactions are confirmed