tachyon-tools Developer Docs

Source: github.com/paxlabs-inc/matrix-core/tachyon Language: Go 1.22+ (daemon), Solidity (contracts corpus), JavaScript (test suite) One-sentence contract: An agent-native Solidity / EVM toolbox that exposes compile, test, simulate, deploy, and call verbs over HTTP API, JSON-RPC, and MCP stdio, with structured I/O, simulation-first safety, idempotent deploys, and policy-gated signing.

Doc	Subsystem	Source files
overview.mdx	This file	-
engine.mdx	Core engine, verb dispatch, envelope types, error taxonomy	`internal/engine/engine.go`, `internal/engine/workdir.go`
compiler.mdx	Solidity compiler, forge build, artifact normalization, ephemeral source workdirs	`internal/compiler/compiler.go`, `internal/forgeutil/run.go`
deployer.mdx	Intent-based deployment, idempotency, CREATE2, on-chain confirmation, registry write-back	`internal/deployer/deployer.go`
wallet.mdx	Signing backends, self-hosted (raw/keystore/env) and embedded (Paxeer DID lane) with policy gate	`internal/wallet/wallet.go`, `internal/wallet/embedded.go`
evm-client.mdx	go-ethereum RPC wrapper, tx building, gas estimation, EIP-1559, raw broadcast, receipt polling	`internal/evm/client.go`, `internal/evm/evm.go`
simulate.mdx	Dry-run simulation, eth_call + optional debug trace, revert capture	`internal/simulate/simulate.go`
tester.mdx	Forge test runner, JSON parsing, suite aggregation, partial failure handling	`internal/tester/tester.go`
abi-encoder.mdx	ABI encoding bridge, JSON-to-Go type coercion for method calls and constructors	`internal/abienc/abienc.go`
registry.mdx	Artifact + deployment index, JSON-file backed, mutex-protected, atomic saves	`internal/registry/registry.go`
chains.mdx	Chain profile manager, presets, custom registration, numeric chain-id fallback, inline RPC	`internal/chains/chains.go`
config.mdx	Runtime configuration, `.kvx` format, env precedence, wallet mode selection, policy profiles	`internal/config/config.go`, `internal/config/kvx.go`
api-server.mdx	HTTP API, REST routes, JSON-RPC passthrough, Bearer auth middleware, structured logging	`pkg/api/server.go`
mcp-server.mdx	MCP stdio server, NDJSON-RPC, tool registry, selftest, error formatting	`pkg/mcp/server.go`, `pkg/mcp/tools.go`
rpc-server.mdx	JSON-RPC dispatcher, `tachyon_*` method routing, envelope wrapping	`pkg/rpc/server.go`
types.mdx	Shared request/response types, envelopes, errors, chain profiles, artifacts	`pkg/types/*.go`
daemon.mdx	Entry point, flag parsing, engine wiring, signal handling, MCP vs HTTP mode	`cmd/tachyond/main.go`

Repo layout

tachyon/
├── cmd/
│   ├── tachyon/          # thin CLI client (main.go)
│   └── tachyond/         # daemon entry point (main.go)
├── pkg/
│   ├── api/              # HTTP REST server
│   ├── mcp/              # MCP stdio server + tool registry
│   ├── rpc/              # JSON-RPC dispatcher
│   └── types/            # shared request/response types
├── internal/
│   ├── abienc/           # ABI encoding bridge
│   ├── chains/           # chain profile manager
│   ├── compiler/         # forge build + artifact normalization
│   ├── config/           # .kvx config parser + loader
│   ├── deployer/         # intent-based deployment
│   ├── engine/           # core verb dispatch + workdir helpers
│   ├── evm/              # go-ethereum RPC wrapper
│   ├── forgeutil/        # forge subprocess runner
│   ├── registry/         # artifact + deployment index
│   ├── simulate/         # eth_call dry-run
│   ├── tester/           # forge test runner
│   └── wallet/           # signing backends + policy gate
├── contracts/            # OpenZeppelin contracts corpus (baked dependency)
├── chains/               # chain presets (presets.json)
├── test/                 # Hardhat/Foundry test suite
└── docs/                 # API docs, architecture docs

Key locked decisions

Agent-native, not human-native. The CLI (cmd/tachyon/) is a thin HTTP client that pipes JSON stdin to the daemon's REST endpoints; the product is the API/MCP/JSON-RPC surfaces. Every response is machine-parseable JSON with stable error codes.
Simulation-first. simulate is a first-class verb. Agents dry-run before they broadcast. Revert data is captured and returned structurally. call supports simulate_only: true for the same effect.
Idempotent by key. Deploys carry an idempotency_key (+ optional CREATE2 salt) so retries do not double-deploy. The registry tracks confirmed deployments and verifies on-chain bytecode before returning cached results.
Keys behind policy. Agents hold scoped capability tokens, never raw keys. Every signature passes a policy gate (Gate.Authorize) that enforces spend caps, contract allow-lists, and chain allow-lists.
Self-contained source uploads. A non-empty sources map on compile/test makes the request self-contained: the engine materializes an ephemeral Foundry project with the baked dependency tree (forge-std, OpenZeppelin, erc4626-tests, halmos-cheatcodes) linked in via symlinks.
Conservative EVM version. Uploaded-source compiles default to shanghai (not cancun) so artifacts do not emit MCOPY, which pre-Cancun chains reject. Callers can override per-chain via CompileRequest.EVMVersion.
Structured errors everywhere. Every failure carries a machine-stable code, human message, and boolean retry flag. Partial results (e.g., test failures with pass counts) are returned in the envelope data field even when ok: false.
Dual wallet modes. self_hosted signs locally with an operator-held key (raw hex, env var, or geth v3 keystore). embedded delegates signing and broadcasting to the Paxeer embedded wallet over the agent-native DID lane, supporting both single-tenant (seed on disk) and multi-tenant (forwarded token, zero seeds) deployments.

Contents

Repo layout

Key locked decisions