Sign inSign up

structs/structs-tsa

By structs

•Updated 2 days ago

The Trans-Planetary Signing Authority is an insecure transaction system for the Structs Guild Stack

Image
0

2.4K

structs/structs-tsa repository overview

⁠structs-tsa

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.

⁠Behavior

  • Every transaction is authorized for its explicit acting player and current signing-key grant. Account numbers, sequences, amounts and permission masks remain exact integers.
  • Signing uses the pinned release CLI, offline direct signatures and independent signature verification. The worker checks current ownership, account state and simulation before transport.
  • SQL stores the immutable signed bytes, hash and account state. A journal on the key volume is persisted before obtaining the one-use SQL send permit. The worker makes one broadcast attempt. Timeout, lost acknowledgement, missing index results and restarts only trigger observation of that same identity. They never automatically replace or resend it.
  • Keys remain reserved until a definitive rejection, an unsent cancellation, or matching transaction bytes and results in a chain block. Unresolved sends survive database loss through the local journal.
  • Startup and periodic reconciliation inventory all local keyring names, including legacy 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.
  • Queue pressure can request extra keys for an existing role. Each request records one eligible source key's exact current grant, the queued work and an idempotency UUID. It never combines grants. With database migration 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.
  • Additional roles are created manually, or from existing explicit onboarding requests. Queue pressure never creates a new player/role. A new role's primary key receives the protocol-required 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.

⁠Build

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.

⁠Configuration

VariableDefault / requirement
DATABASE_URLRequired. Use the dedicated structs_tsa login and the stack's TLS/authentication policy.
TSA_RPC_URLhttp://structsd:26657; current trusted RPC with transaction, block and block-result history.
TSA_LCD_URLhttp://structsd:1317; height-pinned API responses required.
TSA_RPC_FALLBACK_URLDisabled by default. Optional trusted fallback RPC; requires TSA_LCD_FALLBACK_URL.
TSA_LCD_FALLBACK_URLDisabled by default. Matching fallback LCD; set both fallback values empty to disable.
TSA_CHAIN_IDstructstestnet-111; other networks are rejected by this release.
TSA_WORKERS6, 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_KEYS40, valid 1–40; automatic growth counts keys with the copied grant (including supersets) and matching pending requests; requires the capacity migration.
TSA_GAS_PRICENo 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.

⁠Operator commands

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/.

⁠Database and rollout

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.

  1. Build and verify the pinned candidate image. Back up SQL and the full TSA volume.
  2. Complete the paired writer/application readiness checks. Pause enqueueing and drain or explicitly reconcile outstanding legacy sends. Stop the old TSA before enabling the new contract; retain its queue and key history.
  3. Stop the old writer for its paired schema transition. Apply the full Sqitch plan with the explicitly selected 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.
  4. Confirm current source coverage and API readiness, worker login/TLS access, RPC/LCD version and history, and the candidate image digest. Start only the replacement writer/TSA/application services scheduled for this cutover.
  5. Check inventory, pending registrations, pool count, guarded claims and one controlled transaction through definitive inclusion before reopening writes. Verify restart recovery and health.

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.

⁠Validation

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.

⁠November 3 recovery and legacy pool correction

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.

⁠Signing during index advancement

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.

⁠Endpoint fallback while the local node catches up

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.

Tag summary

Content type

Image

Digest

sha256:cd6f28cbd…

Size

166 MB

Last updated

2 days ago

docker pull structs/structs-tsa