New server: gtkm, TKMNet and username services

This sets up a new full node and username RPC entry point on Ubuntu 24.04, using the existing network's two transit peers and two directory authorities. The new server gets its own Tor hostname and relay key. It is not added as a new directory authority, so it continues to use the existing permanent names.

Get the bootstrap kit from the official Gitea repository. It contains public peer descriptors, verified directory pins, helper scripts and user-service units. Each new server creates its own local identities.

1. Install the node and basic dependencies

On the new server, log in as the non-root account that will run gtkm:

sudo apt-get update
sudo apt-get install -y tor python3 curl ca-certificates git
python3 --version
sudo systemctl enable --now tor@default.service

Python 3.11+ is required. Follow Build go-tkmchain with Shield6 from source to compile the node and tools.

For the supplied service, place the built node at:

$HOME/src/go-tkmchain/build/bin/gtkm

If using the separate build worktree or another verified installation path, edit WorkingDirectory and ExecStart in the supplied gtkm.service before installing it. The node must support the current mainnet Shield6 configuration and username RPCs.

2. Clone the public bootstrap kit

On the new server, clone the official repository and check its files:

git clone https://gitea.com/71engrm/new-server-tkmnet.git "$HOME/new-server-tkmnet"
cd "$HOME/new-server-tkmnet"
git rev-parse HEAD
sha256sum -c SHA256SUMS

Record the source commit for your deployment. The checksum file checks file integrity; the approved authority set is carried in approved-network.toml. Obtain it from the official repository and verify any future authority-key changes through the operators' trusted channel. The initializer retains these pins while refreshing their signed public advertisements.

3. Create the new server's Tor onion service

On a fresh server, append this service to /etc/tor/torrc once:

sudo tee -a /etc/tor/torrc >/dev/null <<'EOF'

# This server's own TKM node and TKMNet entry point.
HiddenServiceDir /var/lib/tor/tkmchain-node
HiddenServiceVersion 3
HiddenServicePort 3000 127.0.0.1:3000
HiddenServicePort 39000 127.0.0.1:39000
EOF

sudo tor --verify-config -f /etc/tor/torrc
sudo systemctl reload tor@default.service
sudo cat /var/lib/tor/tkmchain-node/hostname

Allow Tor to create its hostname before reading it. If the file is not ready, check sudo systemctl status tor@default.service and try reading it again. Tor's SOCKS listener should be on 127.0.0.1:9050. Keep existing Tor settings if the host already has services; do not append duplicate mappings. Both P2P and TKMNet can use this server's new onion name with the two distinct forwarded ports above.

4. Generate the complete config

Install the scripts and initialize with the new hostname:

umask 077
mkdir -p "$HOME/.local/lib/tkmnet-bootstrap" "$HOME/.config/systemd/user"
cp "$HOME/new-server-tkmnet/configure.py" \
  "$HOME/new-server-tkmnet/tkmnet_config.py" \
  "$HOME/new-server-tkmnet/approved-network.toml" \
  "$HOME/.local/lib/tkmnet-bootstrap/"

tkm_new_onion="$(sudo cat /var/lib/tor/tkmchain-node/hostname)"
python3 "$HOME/.local/lib/tkmnet-bootstrap/configure.py" \
  --initialize --onion "$tkm_new_onion" --datadir "$HOME/.tkmchain"

The initializer fetches current public advertisements over HTTPS and matches their identities, public keys, onion names and directory pins to the approved configuration. It imports only the configured peer set. gtkm independently verifies descriptor signatures when loading it.

It writes:

~/.tkmchain/gtkm/tkmnet/config.toml
~/.tkmchain/gtkm/tkmnet/peers.json
~/.tkmchain/gtkm/tkmnet/node.env

The complete TOML includes the transit descriptors and directory pins; no manual byte-array editing is required. Its local relay-key path belongs to this new server. gtkm creates that key when the node starts. Initialization refuses to overwrite an existing config or node.env. For an existing node, back up its configuration and use its current peer-refresh manager. This initializer is for new configurations.

5. Enable automatic peer refresh and start gtkm

cp "$HOME/new-server-tkmnet/gtkm.service" \
  "$HOME/new-server-tkmnet/tkmnet-peer-refresh.service" \
  "$HOME/new-server-tkmnet/tkmnet-peer-refresh.timer" \
  "$HOME/.config/systemd/user/"

systemctl --user daemon-reload
systemctl --user enable --now tkmnet-peer-refresh.timer
systemctl --user start tkmnet-peer-refresh.service
sudo loginctl enable-linger "$(id -un)"
systemctl --user enable --now gtkm.service
systemctl --user status gtkm.service tkmnet-peer-refresh.timer --no-pager

The service loads config.toml explicitly and takes this new node's P2P hostname from node.env. It uses the node's redundant built-in mainnet bootnodes rather than overriding them with a single server. It enables tkmname, Tor-only networking and loopback HTTP RPC. The embedded payment prover stays disabled; this node does not automatically sign or send pool payments. The timer refreshes matching public peer advertisements every five minutes; it does not replace authority pins or private identities.

Manage this new node with:

systemctl --user restart gtkm.service
systemctl --user stop gtkm.service
journalctl --user -u gtkm.service -n 40 --no-pager
journalctl --user -u tkmnet-peer-refresh.service -n 20 --no-pager

Do not also run a screen-based node against the same data directory.

6. Sync and verify the network

curl --fail --silent --show-error --max-time 30 \
  -H 'Host: localhost' -H 'Content-Type: application/json' \
  --data '[{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]},{"jsonrpc":"2.0","id":2,"method":"eth_syncing","params":[]},{"jsonrpc":"2.0","id":3,"method":"net_peerCount","params":[]},{"jsonrpc":"2.0","id":4,"method":"tkmname_status","params":[]}]' \
  http://127.0.0.1:8545

Expect chain ID 0x2313 (8979), connected native peers, a current chain head, and two configured directory authorities. eth_syncing: false alone does not prove the head is current. Initial blockchain synchronization and Tor circuit establishment take time. Check the head against a trusted, synchronized node. For a bootstrap archive, follow the verified import instructions on the Downloads page while this node is stopped.

After synchronization, test the actual username route:

curl --fail --silent --show-error --max-time 900 \
  -H 'Host: localhost' -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":5,"method":"tkmname_resolve","params":["@michael"]}' \
  http://127.0.0.1:8545

Use a known registered name on this network. This read-only call must validate its signed record, canonical receiving keys and permanent-name replicas. After a successful operation, tkmname_status should report network readiness. For EOF/TTL errors, check Tor and the peer-refresh service and retry the same operation. Do not replace trusted pins to make an unavailable peer appear ready.

7. Enable Shield6 wallet proving when needed

Consensus verification is included in the node build. To construct payments locally, also install the production public proving parameters from the same source checkout:

cd "$HOME/src/go-tkmchain"
python3 scripts/shield6-release-parameters.py \
  --output "$HOME/.tkmchain/shield6-parameters"
export TKM_SHIELD6_RECIPIENT_PARAMETERS="$HOME/.tkmchain/shield6-parameters"
./build/bin/gtkm wallet interactive --datadir "$HOME/.tkmchain" --language en

Use your actual build directory if different. Follow the wallet's account, stamp and receipt-key registration flow using your own encrypted keyfile. Back up this server's new identities and account state securely. Protect SSH and keep RPC port 8545 and relay port 39000 off the public Internet; Tor provides the configured P2P and TKMNet ingress.

Troubleshooting a node with zero peers

Update older copies of this kit that pinned a single bootstrap server. For the default service paths, install the current unit and restart:

git -C "$HOME/new-server-tkmnet" pull --ff-only
cd "$HOME/new-server-tkmnet"
sha256sum -c SHA256SUMS
cp gtkm.service "$HOME/.config/systemd/user/gtkm.service"
systemctl --user daemon-reload
systemctl --user restart gtkm.service

Keep any local binary-path or data-directory adjustments when updating your service. The current unit lets gtkm try both built-in mainnet bootnodes. A loopback listener is expected: Tor must forward onion port 3000 to 127.0.0.1:3000. The P2P onion hostname comes from the local node.env and the explicit --p2p.onion-hostname service argument.

Older node builds log the raw listener as self=...@127.0.0.1, even when the advertised node address has its onion hostname. This log alone does not prove a connection failure. Check actual peers and the advertised address through local IPC:

"$HOME/src/go-tkmchain/build/bin/gtkm" attach \
  --exec 'admin.nodeInfo.enode' "$HOME/.tkmchain/gtkm.ipc"
"$HOME/src/go-tkmchain/build/bin/gtkm" attach \
  --exec 'net.peerCount' "$HOME/.tkmchain/gtkm.ipc"

Use your actual binary path when different. Keep the node key, relay key and Tor hidden-service directory when repairing connectivity.