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/pdsimage, for the game service and two players; - a local PLC directory, so the reference PDS's
did:plcaccounts 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.