The Trans-Planetary Signing Authority is an insecure transaction system for the Structs Guild Stack
2.4K
The Trans-Planetary Signing Authority signs queued Structs transactions with keys held by a guild stack. This image packages structsd v0.23.0 for testnet structstestnet-111 (upgrade height 3,621,500). Node checks accept v0.22.0 and v0.23.0 across the upgrade boundary. It requires the coordinated v022 signer/database contract; it does not run against the legacy queue schema.
account_* keys. Registered keys are restored to SQL only when current chain ownership/permissions match a ready index. Unregistered, conflicting or uncertain keys remain visible and inactive. Existing claims and managed-registration evidence are preserved.function-signer-key-pool-20261103-capacity, automatic growth is limited to 40 keys per copied permission mask per role, counting current grants that contain that mask and matching unfinished registrations. Unrelated legacy keys and unregistered stubs without requests do not consume that capacity. Manual requests retain the total-role ceiling. Shared throttles do not trigger growth. Available eligible local keys are used first.33554431 grant; subsequent scoped authority still needs to be granted explicitly.The keyring uses the existing test backend. Protect and back up the entire persistent volume: it contains signing keys, recovery phrases and the send journal. SQL contains public key identifiers and transaction evidence, never recovery phrases. Do not share one volume between the old shell workers and this worker.
docker build --platform linux/amd64 -t structs/structs-tsa:v0.23.0 .
The Dockerfile pins the Ubuntu base manifest, official v0.23.0 archive checksum, proof-helper Git commit and Python dependency hashes. Only linux/amd64 is supported by this artifact. OS packages are installed from the Ubuntu repository at build time. Promote the tested image digest rather than rebuilding or deploying a floating latest tag.
The container starts python -m tsa; legacy agent-*.sh scripts are not installed or launched. Preserve the existing volume mount at /var/structs/accounts. /var/structs/chain is CLI configuration, not a chain-node data directory.
Both keyring layouts are supported: legacy .info/.address files directly in the volume, and v022 files in its keyring-test subdirectory. For a legacy volume, the worker recreates the old image's symlink arrangement under the CLI home and reads/writes the original key files in place. An empty nested directory does not hide legacy keys. If both locations contain records, the worker refuses to select one silently; reconcile that mixed layout before starting it. No keys are copied, renamed or regenerated by layout detection.
| Variable | Default / requirement |
|---|---|
DATABASE_URL | Required. Use the dedicated structs_tsa login and the stack's TLS/authentication policy. |
TSA_RPC_URL | http://structsd:26657; current trusted RPC with transaction, block and block-result history. |
TSA_LCD_URL | http://structsd:1317; height-pinned API responses required. |
TSA_RPC_FALLBACK_URL | Disabled by default. Optional trusted fallback RPC; requires TSA_LCD_FALLBACK_URL. |
TSA_LCD_FALLBACK_URL | Disabled by default. Matching fallback LCD; set both fallback values empty to disable. |
TSA_CHAIN_ID | structstestnet-111; other networks are rejected by this release. |
TSA_WORKERS | 6, valid 1–128. Explicit TSA_WORKERS takes precedence; legacy AGENT_TARGET_NUMBER is accepted as a fallback. Tune for host CPU capacity, not signer pool size. |
TSA_ROLE_MAX_KEYS | 40, valid 1–40; automatic growth counts keys with the copied grant (including supersets) and matching pending requests; requires the capacity migration. |
TSA_GAS_PRICE | No implicit value. Exact native price such as 0.025ualpha; required for priced GuildCreate/ReactorRestart operations. Configure for the target node's admission policy. |
TSA_KEYRING_DIR | /var/structs/accounts. |
TSA_HOME | /var/structs/chain. |
Do not put credentials in logs, command-line arguments or copied diagnostics. Docker Compose can supply DATABASE_URL through the existing private environment configuration. RPC/LCD URLs must not contain credentials or redirect to another endpoint.
The healthcheck requires a responsive supervisor, recent successful inventory reconciliation and at least one verified usable local key. An empty installation or a stack waiting for index/role registration stays unhealthy while reconciliation continues. Shutdown stops new claims and waits for bounded in-flight work; configure a 180-second stop grace period. A forced stop remains recoverable, but does not prove a broadcast failed.
The first guild onboarding request is processed automatically once the SQL index and native node satisfy the v0.22 readiness checks. An empty keyring does not require a seed command: the worker generates and retains that request's primary key. Without an existing authorized guild signer, it publishes the proof for approval through the existing external guild approval flow. The key becomes usable after registration is confirmed and indexed. Do not request a duplicate role to repair an existing pending request. known:0 only describes the configured local keyring; check readiness, pending account state and the persistent volume mount before replacing or generating anything manually.
Run these in the candidate container with the same database configuration and persistent key volume. Every new key request requires an explicit permission mask.
python -m tsa reconcile
python -m tsa request-key --role-id 7 --permissions 16 --maximum 40
python -m tsa request-role --name guild-service-two --guild-id 0-1 --permissions 33554431
python -m tsa import-key --name retained-service-key
import-key reads the recovery phrase privately from the terminal or standard input. Never pass it as an argument or environment variable. Imported keys still need current on-chain registration before they can sign.
Requests print and persist a public request UUID before calling SQL. If the acknowledgement is lost, repeat identical arguments with --request-id UUID; do not invent another request. Manual intent files live in tsa-v022/operator-requests/. manual-reload.sh is now an optional immediate reconciliation command; normal startup and periodic operation perform it automatically. manual-role-init.sh delegates to these explicit operator commands.
Reconciliation recovers keys, not lost application requests. It does not reconstruct an old transaction queue or automatically repeat a business action after database destruction. Entries in tsa-v022/outbox/pending/ need exact inclusion/rejection evidence; do not delete them to free a key. Completed history is retained in outbox/completed/.
Deploy structs-pg through function-signer-operator-20261030, including the dedicated worker login and guarded functions. structs_tsa gets selected reads and guarded function calls, without direct mutation grants on game projections or signer tables. The Docker PG startup helper inherits the existing webapp TLS connection rule for this login; an explicitly configured TSA rule is preserved. On an existing server, apply/reload its matching HBA rule as a separate reviewed deployment step. Do not change PostgreSQL/Timescale versions merely to obtain this access rule.
denomination-v1 ledger and v022-1 signer contracts. Restore/catch up source coverage as required by the migration runbook; never overwrite newer indexed state with an exact-height repair.The existing bounded auto-migrator target remains table-signer-tx-20261030-authority-contract until that coordinated switch. Publishing this source does not authorize bypassing the transition gates. After any uncertain send, rollback preserves SQL and volume evidence and must not restart the legacy broadcaster against the new queue.
python3 -m unittest discover -s tests -p 'test_*.py'
docker run --rm --platform linux/amd64 --network none \
-e PYTHONPATH=/workspace -v "$PWD:/workspace:ro" --entrypoint python \
structs/structs-tsa:v0.23.0 /workspace/tests/cli_integration.py
docker run --rm --platform linux/amd64 --network none \
-e PYTHONPATH=/workspace -v "$PWD:/workspace:ro" --entrypoint python \
structs/structs-tsa:v0.23.0 /workspace/tests/inventory_cli_integration.py
docker run --rm --platform linux/amd64 --network none \
-e TSA_DISPOSABLE_TEST=network-none -e PYTHONPATH=/workspace \
-v "$PWD:/workspace:ro" --entrypoint python \
structs/structs-tsa:v0.23.0 /workspace/tests/chain_integration.py
The last test creates a private validator/genesis inside the network-disabled container, simulates and commits a transaction, registers a newly generated key using the actual nonce proof, and signs with that new key. It never reaches testnet.
tests/run_database_integration.py is the workspace harness for full Sqitch deployment on two disposable PostgreSQL instances, first-role bootstrap, real CLI signing, SQL-volume-loss recovery and actual daemon health/shutdown under structs_tsa. Its existing-key recovery case uses the old image's flat volume layout. It requires adjacent structs-pg, the labelled disposable structs-v022-pg image and the local candidate tag structs-v022-tsa-candidate:development; --schema PATH and --image TAG select an exported schema revision and a different built artifact explicitly. It creates an internal Docker network and removes its containers/network afterward. Run the companion signer SQL suites in a disposable database only. Fixture RPCs test recovery behavior; the network-disabled node test separately checks real chain semantics.
To test checkout changes with official image runtimes, without building or deploying a local image, use:
python3 tests/run_database_integration.py --source \
--image structs/structs-tsa:latest --pg-image structs/structs-pg:latest
--pg-image replaces the labelled source-container prerequisite. Both databases
are still newly created, isolated and disposable. The daemon test covers healthy
public fallback, automatic primary recovery and shutdown without duplicate sends.
Recovery selects only prepared, sending, unknown, and accepted submissions, plus unsigned claimed rows. A broadcast queue row can remain after its submission commits; it must not remain in the recovery rotation. This uses the active-submission partial index and preserves recovery after a crash before signing. It does not change send permits or rebroadcast uncertain transactions.
Deploy the TSA recovery update independently of the capacity migration. Automatic growth above an old total-role limit requires the new database migration. No existing account is deleted or granted new permissions by either change. Pool requests still copy one eligible source account's exact grant, require simulation, and serialize outstanding registrations per role. Object-specific grants are not cloned.
Automatic pool registrations take precedence over ordinary eligible pending work after database migration function-signer-key-pool-20261103-priority. Priority follows the current registration of an audited pool request, including renewed attempts; ordinary address registrations retain FIFO ordering. Claims still require an available authorized signer and, for TSA, a fresh local inventory. Priority does not interrupt an already claimed transaction. The change is in TSA’s inventory-aware database claim function and does not require a TSA image rebuild.
Database migration function-signer-20261103-observation-window allows a signing observation to lag the current index by at most five blocks. It preserves current authorization, readiness, immutable signed identity, and pre-broadcast sequence/timeout/simulation checks. Inventory uses the same bounded index-advance window and refreshes its snapshot for each key. Slow attempts beyond the window still defer. Start with six workers on a constrained host; signer account count does not require an equal number of concurrent signing subprocesses.
TSA and sync-state can use different chain endpoints. A current index does not make the local signing node current. TSA requires a supported v0.22.0/v0.23.0 node and the existing v022 database contract, a caught-up node, a current matching index and at least one verified local key. Configure a fallback pair to keep TSA operating through a trusted current public node while the local node catches up:
TSA_RPC_FALLBACK_URL=https://public.testnet.structs.network:26657
TSA_LCD_FALLBACK_URL=https://public.testnet.structs.network
The selector probes at most once per ten seconds across workers. It checks the RPC chain, caught-up flag, v0.22 protocol, and alignment with a ready index. The paired LCD must prove that same height and report the same chain and protocol. If the primary pair fails, both clients switch to the fallback pair. Returning to primary requires three consecutive successful probes spaced at least ten seconds apart. Both pairs failing defers work; it never weakens readiness.
Each transaction attempt and maintenance pass keeps its chosen pair. Switching affects subsequent operations only. Signing and keys remain local. Existing account, grant, sequence, timeout and simulation checks still run. A lost broadcast response remains an unknown submission: another endpoint may observe the saved hash, but it cannot grant another broadcast or a new signed identity.
python -m tsa health reports healthy with endpoint: primary or
endpoint: fallback. /run/tsa/health.json also records the last probe time and
fixed failure codes, without URLs, response bodies or key material. No available
pair reports chain-endpoints-unavailable; stale probes, inventory and missing
ready keys remain unhealthy. A protocol change during a pinned operation can
report chain-node-protocol-unavailable. Inventory retries every ten seconds;
no restart is needed when endpoints recover. Changing endpoint configuration
requires recreating TSA. The signing index must still be current.
Content type
Image
Digest
sha256:cd6f28cbd…
Size
166 MB
Last updated
2 days ago
docker pull structs/structs-tsa