# taiko-mono: What the Taiko Alethia Repository Actually Contains

> Taiko Alethia is described as a based rollup for Ethereum, and taiko-mono is the monorepo behind it. This is what the packages do, how the Docker build works, and where the documentation stops.

**taikoxyz/taiko-mono** — A based rollup protocol for Ethereum🥁 

- Repository: https://github.com/taikoxyz/taiko-mono
- Website: https://taiko.xyz
- Stars: 4,557 · Forks: 2,284
- Language: Rust
- License: NOASSERTION
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/taikoxyz-taiko-mono

## A based rollup, and a monorepo that carries every piece of it

Taiko Alethia is a based rollup on Ethereum. The word based points at who orders transactions: the design puts sequencing in the hands of Ethereum itself rather than a separate sequencer set that the rollup operates. The README states the claim plainly, calling Taiko Alethia "The first based rollup." That single sentence is the whole pitch, and the rest of the repository is the machinery that makes it real.

taiko-mono is not the protocol. It is the workspace that holds the protocol and everything around it. The package table lists eleven entries: balance-monitor, bridge-ui, ejector, eventindexer, fork-diff, nfts, protocol, relayer, supplementary-contracts, taiko-client and taiko-client-rs. Two of those are node implementations, one in Go and one in Rust. One holds the smart contracts. The rest are operations tooling: a bridge front end, a bridge backend relayer, an event indexer, a balance watcher, an NFT contract set, and an ejector service the README describes as being "for operators with issues."

That breadth is the first thing to understand about adopting it. You do not clone taiko-mono to try a rollup. You clone it because you are operating or integrating one of those eleven pieces, and the piece you want lives inside a workspace that also carries the other ten.

## How the workspace is wired: pnpm at the root, Go modules per package

The root package.json is named taiko-mono and marked private, at version 0.23.0. It carries almost no dependencies of its own: lefthook and prettier, both dev-only. Its scripts are three shell wrappers, postinstall, setup:ignores and remove:ignores, all pointing at scripts/setup-local-ignores.sh and scripts/remove-local-ignores.sh. So the root install does not build anything. It wires up git ignore rules for local work and stops there.

The JavaScript side is a pnpm workspace, visible in pnpm-workspace.yaml and pnpm-lock.yaml. The Go side is a single module, github.com/taikoxyz/taiko-mono, declared in the root go.mod at go 1.26.0, with packages/ subdirectories holding the individual services. That module path matters: the Go services are not separate modules with their own import paths, they are packages inside one module, which is why the Dockerfile can build any of them from the repository root.

The dependency list in go.mod tells you what kind of software this is. go-ethereum v1.15.5, the Optimism stack at v1.7.4, prysm v5.3.3, libp2p v0.36.5, Echo v4 for HTTP, GORM with a MySQL driver, RabbitMQ's amqp091-go, goose for migrations, Prometheus client, testcontainers. That is an Ethereum node-adjacent service stack with a database, a message queue, metrics and integration tests. Nothing here is a toy.

The Dockerfile generalises over all of it with one build argument. PACKAGE defaults to eventindexer, and the build runs go mod download at the repository root before changing into packages/${PACKAGE} and compiling cmd/main.go into bin/${PACKAGE}. The runtime stage is alpine with ca-certificates, and the entrypoint is the binary. A single Dockerfile that can produce the indexer, the relayer, the balance monitor or either client is the clearest evidence that the packages share conventions deliberately.

## Installing it and building one service: eventindexer in Docker

The README does not give install steps. It points at docs.taiko.xyz for getting started and at the protocol specs under packages/protocol/docs for depth. What the repository does give you is a Dockerfile that builds any package, so the shortest honest path to a running artefact is a clone plus one docker build with PACKAGE set.

Clone the repository first, then build the event indexer, which is the Dockerfile's default package:

```bash
git clone https://github.com/taikoxyz/taiko-mono.git
cd taiko-mono
docker build --build-arg PACKAGE=eventindexer -t taiko-eventindexer .
```

The build copies the whole repository, runs go mod download against the root module, then compiles packages/eventindexer/cmd/main.go. If the build succeeds you get an image tagged taiko-eventindexer whose entrypoint is /usr/local/bin/eventindexer. Swap PACKAGE for balance-monitor or relayer to build those instead.

On the JavaScript side, the root workspace installs with pnpm, and the postinstall hook runs the local-ignores script automatically:

```bash
pnpm install
```

Expect that to touch git ignore configuration rather than produce a build. The bridge UI, which has its own release line (bridge-ui-v2.18.0, dated 2026-09-04), lives under packages/bridge-ui and is built from its own package scripts, not from the root manifest.

One warning before you start. The README carries a notice that main is under active development and that the release process involves security measures main does not guarantee. For the protocol contracts specifically, it directs you to the taiko-alethia-protocol-v3.0.0 branch for the Unzen fork. Building from main is fine for the services. Building protocol contracts from main is not what the maintainers recommend.

## Two clients, one protocol: the Go and Rust split

The repository ships taiko-client in Go and taiko-client-rs in Rust. Both are described in the package table as Taiko Alethia client implementations. The Rust presence is not incidental: the repository's primary language is listed as Rust, and the release feed shows taiko-alethia-client-rs-v2.2.0 alongside taiko-alethia-client-v2.6.0, both dated 2026-07-15.

Two implementations of the same client is a maintenance cost and a design statement at once. The Go client sits in the same module as the indexer and relayer, so it inherits go-ethereum, the Optimism libraries and the rest of that dependency tree. The Rust client is a separate build with a separate release cadence. If you are integrating, the question is which one your tooling already speaks. If you are running a node, the README's tip is to make sure your node uses the latest version tags for taiko-client and taiko-geth, and to check the node releases page on docs.taiko.xyz.

The risk with parallel implementations is drift. Nothing in the repository layout prevents the two clients from tracking protocol changes at different times, and the release feed shows they are versioned independently. Treat the version tag as the compatibility contract, not the repository commit.

## The licence question the repository does not settle

The README badge says MIT and links to the LICENSE file. The repository metadata says NOASSERTION, which is what GitHub reports when it cannot match the licence file to a known template. Those two statements are not the same, and the discrepancy is worth resolving before you depend on the code.

This is not a hypothetical. A monorepo with eleven packages can carry more than one licence: protocol contracts, a bridge front end and an indexer are different kinds of artefact, and the LICENSE file at the root may not be the last word for every directory. Open LICENSE and check whether per-package licence files exist. I am not giving legal advice; the point is simply that the machine-readable metadata and the human-readable badge disagree, and only one of them is authoritative.

The upgrade cost is the other half of this. Release Please is configured in the repository (release-please-config.json, .release-please-manifest.json), and the releases are per-package: bridge-ui, taiko-alethia-client, taiko-alethia-client-rs each version separately. That means there is no single taiko-mono version to pin. You pin a package, and you track that package's release notes.

## Where the documentation stops and the specs begin

The README is a directory listing with a warning attached. It tells you what the packages are and where to read more, and it does not tell you how to configure any of them. There is no environment variable table, no port list, no config key reference. For a repository whose services need a database, a message queue and an Ethereum endpoint, that is a real gap.

The compensating material is elsewhere. The protocol specs live at packages/protocol/docs/README.md, and the contracts under packages/protocol/contracts/ are documented with NatSpec. If your question is about protocol behaviour, you have a source. If your question is about how to point the relayer at your own MySQL instance, the README is silent and docs.taiko.xyz is where you would look.

A second gap: the README does not document rollback, upgrade or migration procedures for any deployed component. The release process is described only as involving security measures main does not guarantee. For anyone planning to run this in production, that sentence is the whole of what the repository says about release safety, and it is a reason to read the specs and the node releases page rather than the README alone.

This is the pattern to expect from a monorepo maintained by the protocol team itself. The contracts get NatSpec because integrators need them. The operational services get a one-line description because they are used by the team.

## When taiko-mono is the wrong repository to clone

If you want to use Taiko Alethia as a network, you do not need this repository. You need a wallet, the bridge UI, and the docs. Cloning taiko-mono gets you source code for infrastructure you would otherwise consume as a service.

The sharper case: if you want a rollup whose sequencing you control, Taiko Alethia is the wrong design by construction. Based sequencing hands that role to Ethereum, which is the point of the project and also the constraint. A team that needs cheap, fast, privately ordered blocks is looking at a different class of system, and no amount of reading this monorepo changes that.

There is also a scale mismatch. The Dockerfile builds one package per image, and the go.mod pulls in go-ethereum, prysm, libp2p, the Optimism libraries and a MySQL driver. If you only need to read events from the chain, standing up the eventindexer with its database and queue is a heavier commitment than a small indexer script. The repository gives you the production version of that job, not the minimal one.

Finally, the main branch warning is not boilerplate. It is the maintainers telling you that the branch you are reading is not the branch they consider release-safe for protocol contracts. Take them at their word.

## Conclusion

Adopt taiko-mono if you are running or integrating Taiko Alethia infrastructure and can work from the protocol specs under packages/protocol/docs rather than the README. Do not adopt it if you need a single supported release branch: the README warns that main is under active development and points to taiko-alethia-protocol-v3.0.0 for the Unzen protocol contracts. Before anything else, open the LICENSE file, since the repository metadata says NOASSERTION while the README badge says MIT.

## FAQ

### What is taiko-mono?

It is the monorepo for Taiko Alethia, described in the README as the first based rollup. It holds the protocol smart contracts, a Go client, a Rust client, the bridge UI and backend relayer, an event indexer, a balance monitor, an ejector service and supplementary contracts.

### How do I build a taiko-mono service with Docker?

The root Dockerfile takes a PACKAGE build argument that defaults to eventindexer. Build with docker build --build-arg PACKAGE=eventindexer -t taiko-eventindexer . and the resulting image runs the compiled binary as its entrypoint.

### Which branch should I use for the Taiko Alethia protocol contracts?

The README warns that main is under active development and says to use the taiko-alethia-protocol-v3.0.0 branch for the latest protocol contracts, the Unzen fork. It states that the release process involves security measures main does not guarantee.

### What licence does taiko-mono use?

The README badge says MIT and links to the LICENSE file, while the repository metadata reports NOASSERTION. Check the LICENSE file itself, and check whether individual packages carry their own licence terms.

## Sources

- [Issues](https://github.com/taikoxyz/taiko-mono/issues)
- [Project website](https://taiko.xyz)
- [README](https://github.com/taikoxyz/taiko-mono/blob/main/README.md)
- [Releases](https://github.com/taikoxyz/taiko-mono/releases)
- [taikoxyz/taiko-mono on GitHub](https://github.com/taikoxyz/taiko-mono)

---

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