refactor(host_primitives): single home for the Turnkey wire envelope

[pepe-anchor]

Why

Two host binaries have to serve the same Turnkey JSON envelope to the same client.

• parser_gateway: REST in front, gRPC to parser_grpc_server behind. Non-TEE local dev and CI, so it emits a mock bootProof.
• parser_http_server (feat(parser_http_server): HTTP+JSON pivot for TVC public ingress #450): HTTP+JSON inside the enclave, calling parser_app in process, no gRPC hop. This is what gets deployed to the TVC, because Cloudflare in front of app-<uuid>.turnkey.cloud rejects gRPC with 403. It emits a real attested bootProof.

Different transports, different trust levels, one wire contract. The Go visualsign-turnkeyclient and the wallet integrators behind it cannot tell the two apart, and must not be able to.

Two features also land in that envelope during PRS-581: bootProof (#337) and intermediateOutput (#414). If the definition stays inline in parser_gateway, the pivot copies it, and every envelope change from here on gets made twice and kept in sync by hand. The unmerged x402 branch had already grown its own third copy.

So: one home, two importers, and the bootProof difference becomes a parameter instead of a fork.

Downstream, #450, #451 and #452 build on parser_http_server; #449 builds on parser_gateway. Both sides import the envelope from here, which is also what shrinks the PR #304 rebase from "reconcile two envelope definitions" to "add a module".

What

• host_primitives::turnkey becomes the single home for the Turnkey request/response envelope, as the union of both existing definitions.
• bootProof is now an injected value rather than a hardcoded mock: error_response(msg, boot_proof). parser_gateway keeps its stable local-dev mock through a local shim; the enclave pivot supplies a real attested one.
• Construction moved with the types: success_response sits next to error_response, so parse_handler no longer assembles the success envelope field by field in the gateway.
• parser_gateway imports the shared types and keeps the four MOCK_BOOT_PROOF_* constants and the tests that are about its own mock and top-level wire shape. Three tests that would have duplicated coverage now living in host_primitives::turnkey moved there instead of being maintained in both places.
• intermediate_output gained serde(default) alongside its existing skip_serializing_if. Without it the omitted key serialized fine but failed to deserialize, so a response could be written and not read back. Nothing in tree deserializes a response today (both binaries only emit one), which is why no test caught it. The client-direction derives are there so the envelope is symmetric for the out-of-tree clients that do read it, and the new round-trip test is what keeps it that way. Happy to drop those derives and the default until something in tree needs them, if you'd rather not carry them.

No wire change. The gateway's JSON output is byte-identical.

Test evidence

cargo test -p host_primitives -p parser_gateway
  host_primitives: 5 passed
  parser_gateway: 11 passed
cargo fmt --all -- --check: clean
make -C src lint: clean

The gateway test count moves from 13 to 11 because three tests relocated to host_primitives::turnkey, where the types they cover now live: the six-key bootProof assertion (boot_proof_wire_shape_is_exactly_six_camel_case_keys), the empty intermediateOutput omission check, and the Solana chain-metadata discriminator test. host_primitives goes 4 to 5 with the new round-trip test. No coverage was dropped.

The two regression tests that matter both still pass with unchanged constant values: mock_boot_proof_matches_production_wire_shape, error_response_carries_mock_boot_proof.

The "no wire change" claim was checked rather than assumed: a throwaway test reconstructed the pre-refactor struct definitions verbatim from base and byte-compared serde_json output against the new host_primitives::turnkey types across success, error, signature-present, and intermediate-output-present cases. All identical.

One trap worth recording: the x402 branch's TurnkeyResponseWrapper had no rename_all = "camelCase", which the gateway's inline struct did have. Adding boot_proof without it would have serialized as boot_proof instead of bootProof and silently broken the wallet contract. The six-key wire-shape test catches it.

Rollback

Revert the commits. No deploy, no migration, no wire change, so a revert restores the previous state exactly.

Linear

PRS-581

Stack position: base of the PRS-581 stack. #337, #414.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Centralizes the Turnkey wire envelope in host_primitives while preserving the gateway’s existing JSON contract.

Changes:

• Adds shared request, response, boot-proof, and error-envelope types.
• Updates parser_gateway to use shared types with its local mock boot proof.
• Adds wire-shape and serialization tests.

Reviewed changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/parser/gateway/src/main.rs	Replaces local envelope types with shared ones.
src/host_primitives/src/turnkey.rs	Defines the shared Turnkey envelope.
src/host_primitives/src/lib.rs	Exports the new module.
src/host_primitives/Cargo.toml	Adds serialization dependencies.
src/Cargo.lock	Records dependency updates.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 5 changed files in this pull request and generated no new comments.

[shahan-khatchadourian-anchorage]

Right call: one home, boot_proof as a parameter instead of a fork. Verified locally — 5 + 11 tests pass, clippy and fmt --check clean, and no-wire-change holds.

Good: mock stays local to the gateway; parity was byte-compared rather than asserted; test relocation accounted for (13 -> 11, 4 -> 5); the untagged hazard docstring and its test moved with the type; the x402 rename_all trap is covered by the six-key test.

Notes, all non-blocking:

1. Take the offer on the client-direction derives. Drop Serialize on request types, Deserialize on response types. Worth noting none of this trips dead_code — pub items in a lib crate never do, so clippy passing says nothing about reachability here.

   • Serializing a request emits "signature":null,"abiType":null,... and mixes casing (unsigned_payload + networkId). Not a regression — the read path has always accepted that shape (README.md:57) — but Serialize is now what emits it, and nothing pins the request wire shape the way the six-key test pins the response.
   • No inverse of From<ChainMetadataInput> for ChainMetadata, so a caller holding the proto type can't reach the serialize path.
   • Deserialize is stricter than serialize — a response missing one bootProof field fails on missing field deploymentLabel. The round-trip test only reads back what the same type wrote.

   I measured the trim (compiles, 4 + 11 pass): 266 -> 242 source lines, but expanded 2251 -> 883 and rlib 364KB -> 165KB. Side effect: commit 3 becomes moot, since default on intermediate_output goes inert without Deserialize. Keep the attribute anyway; PR drops to two commits. The comment at turnkey.rs:26-28 is aspirational per CLAUDE.md — belongs in the PR body.

   If you'd rather keep the derives, the three things that would make them real: a request wire-shape test, a TryFrom<ChainMetadata> for ChainMetadataInput, and a call on null-vs-omit.

2. default on chain_metadata is a no-op — serde already defaults Option<T> to None (checked). Inconsistent with error/signature, which carry only skip_serializing_if. rename_all on ChainMetadataInput is also dead (both variants explicitly renamed), but that's pre-existing.

3. The enclave picked up serde derives it doesn't use. parser_app links host_primitives, so generated goes from tonic_types to serde, serde_derive, tonic_types. images/parser_app/Containerfile:16-18 reasons about attestation surface and the vsock image has no HTTP surface; #450 enables the feature itself. A non-default turnkey feature covers it. Survives the trim in (1). Minor: health_check's default-features = false on host_primitives is a no-op — no features declared.

4. The duplication that hurts didn't move. #449:1314 and #450:970 hand-build the success envelope field by field, so success_response has one caller and the two PRs motivating it bypass it. The triplicated part is proto -> wire: Chain::from_str_name, the SignatureScheme as i32 match, the base64 encode, the parsed_transaction/payload unwrapping. success_response_from_proto(...) would collapse all three.

5. #304 is the third envelope copy, still open on spec/x402-gated-http-api — worth confirming it rebases onto this rather than reconciling definitions.