README.md

Local testnet #

Brings up the two data servers from the foundations design on loopback and creates the accounts the slice uses. Nothing here contacts a public PDS, PLC directory, relay or AppView.

  • a didbot PDS under agents.localhost, for the AI and NPC accounts;
  • the reference ghcr.io/bluesky-social/pds image, for the game service and two players;
  • a local PLC directory, so the reference PDS's did:plc accounts resolve without leaving the machine.
./testnet/up.sh      # build, start, create accounts, write .testnet/<instance>/accounts.json
./testnet/smoke.sh   # resolve every DID and round-trip a record on each account
./testnet/down.sh    # stop everything and remove .testnet/<instance>/

Each script reads PROTOKILL_TESTNET_INSTANCE, which defaults to default. A named instance gets its own compose project, container, volume, network, port block and state directory, so several can run at once. down.sh touches only its own instance.

PROTOKILL_TESTNET_INSTANCE=a ./testnet/up.sh
PROTOKILL_TESTNET_INSTANCE=b ./testnet/up.sh
PROTOKILL_TESTNET_INSTANCE=a ./testnet/down.sh

fault.sh makes a running testnet misbehave:

./testnet/fault.sh restart pds         # stop one service and start it again
./testnet/fault.sh pause didbot        # freeze it, as a hung peer would be
./testnet/fault.sh resume didbot
./testnet/fault.sh churn player-one --seed 7
./testnet/fault.sh relist player-one   # JSON, for diffing

churn writes sh.protokill.testnet.ping records that create, edit, delete and re-create keys. It saves the expected final set to .testnet/<instance>/churn-<account>-<seed>.json, and relist prints the collection in the same shape, so diff .testnet/<instance>/churn-player-one-7.json <(./testnet/fault.sh relist player-one) checks what survived. The same seed produces the same burst. The expected set snapshots the collection when churn runs, including records it did not write. didbot is a host process, not a container, so pause and resume freeze it with SIGSTOP and SIGCONT. The PDS and PLC directory are paused with docker pause.

up.sh builds didbot from $DIDBOT_SOURCE, /data/dev/didbot by default, with CARGO_TARGET_DIR under this worktree and never writes into that checkout. The PLC directory image is built from a pinned did-method-plc revision the first time; the reference PDS image is pinned by digest. Both stay in the local Docker image store.

Ports and their defaults are in testnet/lib.sh. A named instance derives a block of three ports from its name; PROTOKILL_TESTNET_PORT_BASE sets the first port explicitly, and each port can also be moved on its own with its TESTNET_*_PORT variable. State, credentials and didbot's local certificate authority live in the git-ignored .testnet/<instance>/ directory, which down.sh removes.

The reference PDS keeps its data in the <project>-pds-data volume, and didbot keeps its store and signing keys under .testnet/<instance>/didbot-data, so both keep their accounts and records across fault.sh restart. The PLC directory holds its store in memory: after fault.sh restart plc every did:plc DID document is gone, so the service and player accounts stop resolving even though their records are still in the reference PDS. down.sh removes the instance's volume, didbot's data and the rest of its state directory.

The reference PDS's accounts are did:plc and resolve through the local PLC directory; didbot's are did:web under agents.localhost. The handle rules live in testnet/lib.sh and testnet/up.sh.