EVM Blockchain Configuration | Ceramic documentation

On this page

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:

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:

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

Optional Settings

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