# iotex-core: Building and Operating the IoTeX Blockchain

> iotex-core is the Go implementation of the IoTeX Layer-1 protocol, including the server, ioctl CLI, consensus components, EVM integration, state storage, APIs, and an optional IOSwarm transaction-validation coordinator.

**iotexproject/iotex-core** — Official implementation of IoTeX blockchain protocol in Go. An ultra-efficient EVM blockchain offering 1000 TPS with instant 1-block finality. Perfect for DeFi, DePIN tokenomics, Identities, and any trusted logic requiring Web3 composability

- Repository: https://github.com/iotexproject/iotex-core
- Website: https://iotex.io
- Stars: 1,618 · Forks: 384
- Language: Go
- License: Apache-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/iotexproject-iotex-core

## What iotex-core Implements for Node Operators

iotex-core is the official Go implementation of the IoTeX blockchain protocol. It is aimed at protocol contributors, node and delegate operators, wallet or application engineers, and developers who need direct access to IoTeX execution and networking internals. The repository produces a server and an ioctl command-line client. Its packages also expose components such as consensus, peer-to-peer communication, block synchronization, API services, transaction handling, state management, and system contracts.

The repository describes IoTeX as modular infrastructure for DePIN projects, meaning decentralized physical infrastructure networks. Its example use cases range from wireless hotspots to solar-powered home batteries. That market positioning does not make iotex-core a device agent. This project is the blockchain software beneath such networks. It does not provide the physical devices, token contracts, application interfaces, or incentive policies for an individual DePIN deployment.

The implementation is a complete blockchain node codebase rather than a narrow EVM library. The directory layout supports that distinction. Entries such as blockchain, consensus, actsync, p2p, state, db, api, gasstation, and server correspond to separate protocol or operational concerns. The ioctl directory provides the user-facing command surface, while action, systemcontracts, and systemcontractindex cover transaction and protocol support. This makes the repository useful both for running software and for changing protocol behavior, but it also means upgrades can affect several coupled subsystems rather than one isolated package.

## iotex-core Request and State Flow

The visible package structure describes a conventional blockchain data path. Transactions enter through the action handling area and are associated with the actpool. Block synchronization has a dedicated actsync package, while accepted blocks are processed through blockchain and consensus components. State changes are handled under state and persisted through db. Separate API, p2p, gasstation, and nodeinfo packages expose network and operational concerns without collapsing them into one server component.

The optional IOSwarm component adds a more specific transaction-validation path. According to the README, a delegate-side coordinator observes pending transactions from actpool, obtains account-state information from stateDB, and dispatches validation tasks to external agents over gRPC. A StateDiff stream supplies state updates to agents configured for L4 validation. The documented levels progress from signature verification at L1 to nonce and balance checks at L2, full EVM re-execution at L3, and local state managed through BoltDB at L4.

IOSwarm is explicitly described as shadow mode. Its results are observational and do not affect consensus or block production. That boundary matters. An operator should not mistake agent participation or its documented validation levels for authority over final block acceptance. The coordinator also exposes an HTTP monitoring API on port 14690, with `/api/stats` and `/swarm/shadow` documented as endpoints. The repository contains a dedicated ioswarm directory and README, but the main README excerpt does not provide enough information to assess agent deployment, failure handling, compatibility with every node configuration, or the security consequences of its secret and signing-key settings.

## Building iotex-core with Go and Make

The README's source-build tutorial begins by cloning the repository and entering its directory. The listed clone command uses SSH, so the machine must already be able to access GitHub through that transport.

```bash
git clone git@github.com:iotexproject/iotex-core.git
cd iotex-core
```

The README says the general build targets the server and ioctl client. It describes a separate broader target that also builds tools including the injector.

```bash
make
```

Use `make all` when those additional targets are required:

```bash
make all
```

The documented unit-test target is:

```bash
make test
```

The Makefile defines tests with `CGO_ENABLED=1`, so the build environment also needs a working C toolchain when using this target. The README separately requires Protoc 3.6.0 or later only when protobuf messages are rebuilt.

There is a version inconsistency worth resolving before adoption. The README table lists Golang 1.22.12 or later, while go.mod declares `go 1.25.14`. The Dockerfile uses `golang:1.27-alpine`. For a reproducible release build, the safest interpretation is to use the toolchain required by the checked-out release's go.mod rather than choosing the oldest version printed in the README. The repository is not archived, and its last push was on 2026-10-15. Recent releases include v2.5.1 on 2026-10-04, v2.5.0 on 2026-09-28, and v2.4.5 on 2026-09-15. This supports active code movement, but it does not remove the need to review release notes and migration requirements.

## Starting a Standalone iotex-core Server

After building, the README uses `make run` to start or resume a standalone blockchain server. This is a local development-style operation, not complete delegate onboarding. The README sends delegate setup to the separate IoTeX Delegate Manual and points to the `iotex-bootstrap` repository.

```bash
make run
```

The command depends on the server binary and configuration produced by the build. The provided tutorial does not show a minimal `config.yaml` or genesis setup for `make run`, so it does not establish the values needed for joining a public network. Readers must not copy generic configuration assumptions into this node.

For a deliberately clean restart, the README documents:

```bash
make reboot
```

That operation is materially different from recovery. A corrupted or missing state database can prevent startup even when the block database remains intact. The documented example failure is failure to obtain the factory's height from the underlying database. For that case, the README directs operators to run the recovery target and then try `make run` again.

```bash
make recover
```

The available text does not document what `make recover` preserves, how it reconstructs state, or whether it is appropriate for every database inconsistency. It should therefore be treated as a targeted response to the documented failure, not a generic repair procedure.

Docker offers a second distribution path. The README gives `make docker` as the local image build command. The checked-in Dockerfile performs a multi-stage build, copies `iotex-server`, `iotex-actioninjectorv2`, `iotex-addrgen`, and `ioctl` into an Alpine image, installs `logrotate`, and defaults the container command to `iotex-server`. Production operators still need to supply correct configuration, genesis data, persistent storage, networking rules, and operating-system support.

## Running Optional IOSwarm Validation Locally

IOSwarm is an optional extension documented for existing delegates. Its quick deployment uses a named Docker image and adds configuration under the `ioswarm` key. The example binds gRPC to localhost and the monitoring API to localhost, which avoids directly exposing either service through the Docker port mapping.

```yaml
ioswarm:
  enabled: true
  grpcPort: 14689
  swarmApiPort: 14690
  maxAgents: 100
  taskLevel: "L4"
  shadowMode: true
  pollIntervalMs: 1000
  masterSecret: "<your-secret>"
  epochRewardIOTX: 0.5
  diffStoreEnabled: true
  diffStorePath: "/var/data/statediffs.db"
  rewardContract: "0x236CBF52125E68Db8fA88b893CcaFB2EE542F2d9"
  rewardSignerKey: "<hex-key>"
  reward:
    delegateCutPct: 10
    epochBlocks: 1
    minTasksForReward: 1
    bonusAccuracyPct: 99.5
    bonusMultiplier: 1.2
```

The configuration selects L4 work, enables shadow mode, limits agents, controls polling, stores state differences under `/var/data`, and configures reward-related values. A placeholder secret and signing key must not be treated as production values. The README also says agents can earn IOTX rewards per epoch through on-chain settlement, which introduces credential and financial configuration beyond ordinary node operation.

The documented Docker restart removes and recreates a container named `iotex`. That command is not harmless for an unfamiliar environment because it assumes the existing container name and mounted paths are correct. It also maps the gRPC and HTTP services only to host loopback. The README advises using nginx for TLS termination. Operators should first inspect the complete `ioswarm/README.md`, because the main excerpt ends partway through a note and does not show agent startup or complete security guidance.

The real limitation is architectural: IOSwarm in shadow mode adds coordination, state synchronization, monitoring, secret handling, and agent infrastructure without granting external agents control over consensus. It is suitable only for delegates who understand those operational costs and have a reason to run observational validation.

## iotex-core Constraints, Upgrades, and Apache-2.0 Use

iotex-core is a poor fit for developers who only need to submit transactions, query a public IoTeX endpoint, or deploy a Solidity contract. The README positions ioctl as the interaction tool and links to separate CLI documentation, while application teams can use the IoTeX website and DePIN Scan for network and project information. Building this repository is justified when operating protocol software or modifying node behavior, not simply because an application uses IoTeX.

It is also a poor fit for environments that require an effortless build. The Go version declarations conflict, native dependencies may be needed for tests, protobuf regeneration adds Protoc, and container operation requires persistent data and configuration. The repository also contains many protocol subsystems whose interfaces can change together. Upgrading a node therefore means more than replacing a binary. The operator must account for configuration compatibility, database compatibility, consensus behavior, API expectations, and any version-specific migration notes. The documentation does not specify a universal upgrade procedure or rollback policy.

A meaningful alternative is to depend on a network node through ioctl or the documented CLI interface without forking iotex-core. That approach avoids ownership of consensus, P2P, block synchronization, state storage, and database operations. The trade-off is direct control: application teams cannot alter protocol code or run their own delegate from a client configuration alone. iotex-core becomes the relevant choice when that control is part of the requirement.

The project is licensed under Apache-2.0. That license permits use and modification under its stated terms, but operators still need to observe its notice, patent, and redistribution requirements. The IoTeX trademark, network configuration, smart-contract permissions, reward signer key, and operational obligations are separate from source-code licensing. Nothing in the repository description turns configuration or on-chain rewards into permissionless decisions.

## Conclusion

Adopt iotex-core if you need to build an IoTeX server, work on the protocol, or operate the included ioctl CLI. Do not adopt it as an application framework or assume the documentation alone is enough for delegate deployment. Before starting, verify the intended release tag, reconcile its Go version with the build image, confirm your node configuration and genesis file, and review the state and consensus dependencies for your target environment.

## FAQ

### What is iotex-core used for?

It is the official Go implementation of the IoTeX blockchain protocol. The repository includes the server, ioctl CLI, consensus, networking, synchronization, API, state, and transaction-processing components.

### How do I build iotex-core from source?

Clone the repository, enter its directory, and run `make`. The repository documentation also provides `make all` for broader targets and `make test` for unit tests.

### What should I check if an iotex-core server cannot start?

The README identifies a corrupted or missing state database, while a block database may still be normal. For the documented case where the factory's height cannot be obtained from the underlying database, it directs operators to run `make recover` and then retry `make run`.

## Sources

- [iotexproject/iotex-core on GitHub](https://github.com/iotexproject/iotex-core)
- [License: Apache-2.0](https://github.com/iotexproject/iotex-core/blob/master/LICENSE)
- [Project website](https://iotex.io)
- [README](https://github.com/iotexproject/iotex-core/blob/master/README.md)
- [Releases](https://github.com/iotexproject/iotex-core/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/iotexproject-iotex-core