inertia/tintoy repository overview

⁠Tin Toy

Tin Toy is a small Dockerized Hive testnet built around Tinman⁠. The current core image applies sample-snapshot.json to a temporary fast-generation node, hands the resulting blockchain to a seed node, configures 21 deterministic witnesses, and waits for normal block production.

The restored image intentionally contains only the verified core path. The historical Jussi, nginx, Postgres, Hivemind, condenser, and Tinman-server files remain as reference scaffolding; those services are not started or exposed by the current image.

⁠Quick start

Run the published image from Docker Hub⁠:

docker run --rm --platform linux/amd64 --name tintoy \
  -p 8092:8092 \
  -p 2001:2001 \
  inertia/tintoy:1.29.0

You need a running Docker daemon configured for Linux containers. Python, Tinman, and Hive are included in the image. The commands use a Bash-compatible shell; on Windows, use WSL or Git Bash.

ARM hosts need AMD64 emulation to use the pinned Hive image. Docker Desktop includes emulation; see Docker's multi-platform guide⁠.

Version tags identify the Hive build. The org.opencontainers.image.version label records that version; io.hive.blockchain.version records the version reported by the testnet binary. These values can differ in upstream releases.

The core release replaces the historical stack on latest. Use legacy-2021 if you need the previous image. For the current release, wait for the bootstrap completion message below, then verify RPC on port 8092.

⁠Build from source

Building from a checkout requires Docker and internet access to download the base images and Python packages.

The default image combination is verified on linux/amd64:

• Tinman: registry.gitlab.syncad.com/hive/tinman@sha256:c6d796d1...
• Hive testnet: registry.gitlab.syncad.com/hive/hive/testnet@sha256:89be820e...
• Hive blockchain version: 1.29.0

The Dockerfile pulls the published Tinman image, pinned to the verified digest of registry.gitlab.syncad.com/hive/tinman:develop at Tinman revision f3adf9ed910069602a6a322586d7c825db953933. Build directly from this repository:

docker build --platform linux/amd64 \
  -t tintoy:local \
  .

The commands use your selected Docker context. To use a remote Docker daemon, replace docker with docker --context <context-name> consistently in the build and run commands.

To test another immutable Tinman or Hive image, override the build arguments and keep the Tinman revision, Hive build version, and reported blockchain version labels synchronized with the selected images:

docker build --platform linux/amd64 \
  --build-arg TINMAN_IMAGE=registry.gitlab.syncad.com/hive/tinman@sha256:<digest> \
  --build-arg TINMAN_REVISION=<full-tinman-commit> \
  --build-arg HIVE_IMAGE=<repository>@sha256:<digest> \
  --build-arg HIVE_VERSION=<hive-build-version> \
  --build-arg HIVE_BLOCKCHAIN_VERSION=<reported-blockchain-version> \
  -t tintoy:test .

Floating Tinman and Hive tags are not compatibility evidence. Use digests for any result that should be reproducible.

⁠Hive 1.28.7 release

The upstream Hive 1.28.7 release⁠ leaves its testnet blockchain version at 1.28.6; only the mainnet version was bumped to 1.28.7. The testnet image contains the release's peer-handling fixes without changing that upstream version definition.

Build this variant with the pinned release image:

docker build --platform linux/amd64 \
  --build-arg HIVE_IMAGE=registry.gitlab.syncad.com/hive/hive/testnet@sha256:4b5720852668ab9cbdd41e2f16543c3ccd30fb3fc217174d312f38ff86867c79 \
  --build-arg HIVE_VERSION=1.28.7 \
  --build-arg HIVE_BLOCKCHAIN_VERSION=1.28.6 \
  -t tintoy:1.28.7 .

⁠Hive 1.28.8 release

The upstream Hive 1.28.8 release⁠ defines its testnet blockchain version as 1.29.0; the mainnet version is 1.28.8. The 1.28.8 image tag identifies the release, and the blockchain version label follows the upstream testnet binary.

Build this variant with the pinned release image:

docker build --platform linux/amd64 \
  --build-arg HIVE_IMAGE=registry.gitlab.syncad.com/hive/hive/testnet@sha256:402f79f6f1967009dc0ccea4f84cdc94b16a80b59ec27f2aef78730c0bcc4694 \
  --build-arg HIVE_VERSION=1.28.8 \
  --build-arg HIVE_BLOCKCHAIN_VERSION=1.29.0 \
  -t tintoy:1.28.8 .

⁠Run a local build

Start a fresh container and publish the core RPC and p2p ports:

docker run --platform linux/amd64 --name tintoy-modernization \
  -p 8092:8092 \
  -p 2001:2001 \
  tintoy:local

Allow several minutes for bootstrap. It is complete only after the logs contain:

tintoy: snapshot applied and seed node is producing

The active endpoints are:

For an ephemeral container, add --rm. Do not expose this testnet to untrusted networks: its witness and account keys are deterministic test keys.

⁠What startup does

bootstrap.sh owns the full lifecycle:

1. Start a pristine Hive fast-generation node on internal port 9990.
2. Apply sample-snapshot.json through Tinman's compatibility runner.
3. Stop the bootstrap node and move its blockchain into the seed data directory.
4. Force-replay that blockchain into the production node on port 8092.
5. Configure 21 deterministic witnesses and wait for the chain to produce.

The compatibility runner discovers live chain properties, including the account-creation fee, key prefix, authority limit, chain ID, and active hardfork. The procedural witness keys in the current core flow use an empty derivation secret; the legacy SHARED_SECRET environment variable is not a security boundary for this image.

⁠Verify the node

Read the dynamic global properties from the published RPC endpoint. This example uses curl and jq on your host:

curl -sS http://127.0.0.1:8092 \
  --data '{"jsonrpc":"2.0","method":"database_api.get_dynamic_global_properties","params":{},"id":1}' \
  | jq

For a remote Docker daemon, replace 127.0.0.1 with the Docker host's reachable address.

Run it twice a few seconds apart and confirm that head_block_number increases.

⁠Refresh the sample snapshot

Snapshot refresh is normally a maintainer task:

1. Install Tinman as described in its README⁠.

2. Snapshot a trusted mainnet RPC endpoint:

   tinman snapshot -s http://127.0.0.1:8090 -o snapshot.json
   

   Copy

3. Replace the sample with a smaller deterministic selection:

   tinman sample -i snapshot.json -o sample-snapshot.json
   

   Copy

4. Remove or archive the full snapshot outside this repository.

The current 2,000-account sample imports 1,998 non-genesis accounts. The original core combination (Tinman 911e472, Tin Toy 97042dd) passed on native Linux AMD64 and Docker Desktop on Apple Silicon using AMD64 emulation.

The current published Tinman pin (f3adf9e) also passed fresh Docker Desktop AMD64-emulation bootstraps with both Hive 1.29.0 and 1.28.7: all 2,000 sample accounts were present, all 21 replacement witnesses were registered, 21 witnesses were scheduled, and the head advanced from 169 to 172 in both runs.