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

Repo layout

tachyon/
├── cmd/
│   ├── tachyon/          # thin CLI client
│   └── 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 is a thin client; 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.
Idempotent by key. Deploys carry an idempotency_key (+ optional CREATE2 salt) so retries don't double-deploy. The registry tracks confirmed deployments.
Keys behind policy. Agents hold scoped capability tokens, never raw keys. Every signature passes a policy gate (spend cap, allow-list, chain allow-list).
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 linked in.
Conservative EVM version. Uploaded-source compiles default to shanghai (not cancun) so artifacts don't emit MCOPY, which pre-Cancun chains reject.
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.

Contents

Repo layout

Key locked decisions