Chaintable write node

Fork of circlefin/arc-node, with Chaintable pipeline patches.

Architecture

This repo runs Arc's execution layer with a Chaintable pipeline-compatible tracer. It exposes block headers, transactions, call traces, receipts, events, and state diffs through trace_debankBlock. An external background-tracer / ETL process calls this RPC and uploads the results to S3 + Kafka; the writer itself does not upload to either service (see pipeline's architecture).

• Block headers + state diffs → Kafka + S3 → leafage-evm: a lightweight EVM executor serving state queries.
• Block files (transactions · call traces · receipts · events) → S3 → Chaintable's transaction/trace indexing pipeline.

Arc write node (this repo)
        │ trace_debankBlock RPC
        ▼
background-tracer / ETL
        ├─ block headers + state diffs ─→ Kafka + S3 ─→ leafage-evm
        └─ block files ─────────────────→ S3 ─→ Chaintable indexing pipeline

Chaintable images

The public image workflows build the execution and consensus nodes from this repository for linux/amd64 and linux/arm64:

• Base image: public.ecr.aws/b2h7a5c4/chaintable/arc-node
• Writer alias: public.ecr.aws/b2h7a5c4/chaintable/arc-writer (the same manifest)
• Consensus image: public.ecr.aws/b2h7a5c4/chaintable/arc-consensus

Same-repository PRs, default-branch pushes, and manual builds use an eight-character commit tag; per-architecture base tags append -amd64 or -arm64. GitHub Releases use v<base-version>-ct.N tags. Use a fixed tag after its build and manifest jobs succeed; provisioning all three public ECR repositories is a maintainer prerequisite.

The execution images contain arc-node-execution and arc-snapshots; the consensus image contains arc-node-consensus and arc-snapshots. Both use Debian 12 with Bash, sh, and coreutils for Kubernetes init/runmode scripts, retaining user arc (UID/GID 999) and their direct binary entrypoints. The consensus client and external ETL remain separate services. The Arc documentation below describes the underlying client, not the Chaintable image publication process.

For local image builds, initialize the public submodules and use the existing Bake target (including its certificate context):

git submodule update --init --recursive
GIT_COMMIT_HASH="$(git rev-parse HEAD)" \
GIT_SHORT_HASH="$(git rev-parse --short=8 HEAD)" \
GIT_VERSION="$(git describe --tags --always --dirty)" \
docker buildx bake arc-execution --set arc-execution.tags=arc-writer:local

For consensus, use target arc-consensus and tag override --set arc-consensus.tags=arc-consensus:local with the same build metadata.

See CONTRIBUTING.md and SECURITY.md for the Chaintable contribution and vulnerability-reporting processes.

---

The Economic OS for the internet

Important

Arc is currently in testnet, and this is alpha software currently undergoing audits.

Arc is an open EVM-compatible layer 1 built on Malachite consensus, delivering the performance and reliability needed to meet the new demands of the global internet economy.

Features

• USDC as Gas - Pay gas in USDC for low, predictable fees on any transaction
• Deterministic Sub-second Finality - Near-instant settlement finality powered by Malachite BFT consensus engine
• Circle Platform Integration - Integrates with Circle’s full-stack platform (e.g., USDC, Wallets, CCTP, Gateway) to help you go from prototype to production faster
• (Coming soon) Opt-in Configurable Privacy - Native privacy tooling enables selective shielding of sensitive financial data while preserving auditability

Documentation

• 🚀 Execution - Execution binary and configuration
• 🗳️ Consensus - Consensus binary and configuration
• More: see Arc developer docs for guides, APIs, and specs

Install and Run a Node

Install

See Installation for how to obtain the Arc node binaries or Docker images (pre-built, from source, or via Docker).

Run

See Running an Arc Node for configuration and startup (binaries or Docker Compose).

Development

Repository setup

Clone the repository (or pull the latest changes). This repository uses Git submodules; initialize and update them with:

git submodule update --init --recursive

Tip: To automatically fetch submodules on git pull, run in the repo root:

git config submodule.recurse true
git config fetch.recurseSubmodules on-demand

Prerequisites

• Rust
• Docker
• Node.js
• Foundry
• Hardhat
• Protobuf
• TypeScript
• Yarn
• Buf

Install required tools on macOS with Homebrew:

brew install protobuf node yarn bufbuild/buf/buf

curl -L https://foundry.paradigm.xyz | bash
foundryup

Note: Hardhat only supports even Node.js versions (e.g., 20.x, 22.x). Odd versions like 25.x are not supported. See Hardhat's Node.js support policy for details.

Install JavaScript dependencies:

npm install

Build

Build the project:

make build

Code Quality

Format and lint your code:

make lint

Testing

The test suite includes unit tests, integration tests, contract tests, and smoke tests.

Run tests:

# Unit tests (Rust + linting)
make test-unit

# Integration tests
make test-it

# Contract tests (Solidity)
make test-unit-contract

# Smoke tests (end-to-end validation)
make smoke

# Run all tests
make test-all

Coverage

Generate and view test coverage (requires cargo-llvm-cov):

# Install cargo-llvm-cov on macOS with Homebrew (one-time setup)
brew install cargo-llvm-cov

# Generate coverage for unit tests
make cov-unit

# Generate HTML report and open in browser
make cov-show

Local Testnet

Launch a full local testnet with 5 execution nodes, 5 consensus nodes, plus Prometheus, Grafana, and Blockscout:

make testnet

Note: If your development environment requires installing custom CA certificates, you can add them to the deployments/certs directory. They must be PEM-encoded and have a .crt extension. They will be automatically installed into the Docker images at build time.

To export a certificate from your system's keychain (macOS):

security find-certificate -p -c '<cert name>' > deployments/certs/<cert name>.crt

Interact with the testnet:

# Send tx load (usage: make testnet-load RATE=1000 TIME=60)
make testnet-load

# Stop the testnet
make testnet-down

# Clean up all resources
make testnet-clean

For an in-depth look at system design and individual components, check out the Architecture Guide. For architectural decisions and their rationale, refer to our Architecture Decision Records (ADRs).

Contributing

We welcome contributions! Please follow these steps:

1. Format and lint: make lint
2. Build: make build
3. Test: make test-unit
4. Check coverage: make cov-show

For more details, see our Contributing Guide.

Resources

• Arc Network - Official Arc Network website
• Arc Documentation - Official Arc developer documentation
• Reth - The underlying execution layer framework
• Malachite - BFT consensus engine
• Local Documentation - Implementation guides and references

Acknowledgements

This project is open-source software licensed under Apache 2.0. It is built from a number of open source libraries and inspired by others. We would like to highlight several of them in particular and credit the teams that develop and maintain them.

Malachite - Malachite, a flexible BFT consensus engine written in Rust, was originally developed at Informal Systems and is now maintained by Circle as part of Arc. We thank Informal Systems for originating and stewarding Malachite, and for their continued contributions to the project.

Reth / Paradigm - Reth is an EVM execution client that is used in Arc’s execution layer via the Reth SDK. We thank the Paradigm team for continuing to push the envelope with Reth and for their continued emphasis on performance, extensibility, and customization, as well as their commitment to open source. Additionally, we’re big fans of the Foundry toolchain as well!

libp2p - libp2p is used extensively through the arc-node consensus layer, and we thank the team for their development of it.

Tokio - Tokio is used extensively throughout the consensus and execution layers, and we are grateful to the team for their continued development and maintenance of it.

Celo - USDC is the native token on Arc and supports interacting with it through an ERC-20 interface; this “linked interface” design was first (as far as we know) pioneered on Celo, and we’d like to credit the team for devising it.

Alloy-rs - Alloy is used throughout the consensus and execution layers, and we are very thankful to the team for this excellent library.

Revm - Revm is used via the Reth SDK in the execution layer as the core EVM implementation. We thank the team for their continued development and maintenance of it.

Hardhat / Nomic Foundation - We thank the team for their continued development of the Hardhat toolchain.

Viem - We thank the team for their continued development of Viem and other libraries.