docs: explain app proofs and boot proofs#669
Open
emostov wants to merge 4 commits into
Open
Conversation
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
Followup after re-reading the source Slack thread: - document the public get_boot_proof / get_latest_boot_proof / list_app_proofs endpoints so verifiers know where to fetch Boot Proofs - document the multi-replica behavior (per-enclave Ephemeral Keys, different responses signed by different keys, cache by Ephemeral key) - document the Anchorage-style pattern of bundling App Proof + Boot Proof in a single response, and point at tvc_server.go - add public_api_server.go and tvc_server.go to the code-pointers list
Contributor
Author
|
Followup after re-reading the source Slack thread — I had missed a few customer-relevant points from later in the conversation. Added in 6fd03a4: New section: "Fetching proofs as a verifier"
New section: "Multiple replicas and per-enclave Ephemeral Keys"
Code pointers expanded to include Doc is now 132 lines — within the original 150-250 target range. |
- Remove all references to internal tkhq/mono repo paths and file locations; rephrase to describe behavior, not implementation. - Remove the 'Caching Boot Proofs' section entirely. - Remove the 'Multiple replicas and per-enclave Ephemeral Keys' section entirely. - Remove the 'Where this lives in the code' section (was wall-to-wall tkhq/mono links); App Proof bytes-on-the-wire reference now points to the public Rust + TypeScript SDK verifier implementations from the 'Who produces it' subsection. - Drop named-customer reference (Anchorage) from the bundling pattern paragraph; describe the generic pattern instead. - Soften the cross-link from security/turnkey-verified.mdx so it no longer promises a 'where each proof is produced in the codebase' walkthrough.
- Remove all remaining implementation-level narration (producer reads X then Y then Z, bundle-pattern step-by-step instructions, 'who produces it' sub-sections describing internal mechanics). - Drop the 'Bundling the verifiability chain' subsection entirely; the generic public-API description of fetching proofs covers what a customer needs to know. - Collapse Boot Proof / App Proof producer paragraphs into single what-level sentences; no how-it-works narration. - Keep cryptography, JSON wire format, public API endpoints, and the trust-boundary discussion (Quorum vs Ephemeral Key) untouched per reviewer scope.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation
Capture knowledge from a Slack thread where Zeke and Narimon explained how Boot Proofs and App Proofs work to Annie. As Annie put it: "this should be in a wiki, don't lose it to Slack retention." Source thread: https://turnkeycrypto.slack.com/archives/C07TWDK573N/p1779387688273429
We already have
security/turnkey-verified, but it's the customer-facing summary and isn't explicitly TVC-positioned. Per Arnaud's suggestion, this PR adds a dedicated "Proofs and Verification" page under the TVC section that goes into architectural depth, with a cross-link from the existing Turnkey Verified page.What's in this PR
products/verifiable-cloud/proofs-and-verification.mdx. Sections: Overview, Boot Proof, App Proof, Why the Ephemeral Key and not the Quorum Key, Verification flow (the 5-step list, copy-pasteable for verifier implementors), Where this lives in the code.docs.json.security/turnkey-verified.mdxdirecting readers to the deeper TVC page.The substance is unchanged from the Slack thread — the writing is re-toned but every technical claim (trust-boundary argument, share-set collusion caveat, AWS attestation caveat, the 5-step verification flow, the "Ephemeral Key proves what code generated the output" punchline) is preserved.
Credits
Substance comes from @emostov (Zeke) and Narimon Farhangi (@narimonf). Posting the doc; not the original author of the technical explanation.
Reviewers
cc @emostov @narimonf