docs: align TEE attestation docs with the no-yield design

[pbeza]

Splits the TEE attestation doc changes out of the async-attestation tests PR (#3715) so that PR stays test-only. Stacked on top of #3715; retarget to the base branch once #3715 merges.

Closes #3825

[Copilot]

Pull request overview

Aligns the repository’s TEE attestation documentation with the shipped “no-yield” promise-chain submit_participant_info flow, replacing the superseded yield/resume + timeout design and updating operator-facing troubleshooting examples accordingly.

Changes:

• Rewrites docs/design/attestation-verifier-contract.md to describe the no-yield verify_quote -> resolve_verification promise chain, including deposit-forwarding and failure handling.
• Updates the re_verify reference to its current source location.
• Refreshes localnet/TDX guide error-message examples to match current on-chain error strings.

Reviewed changes

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

File	Description
docs/running-an-mpc-node-in-tdx-external-guide.md	Updates the on-chain receipt error example to match the current attestation failure message.
docs/localnet/tee-localnet.md	Updates the localnet ExecutionError(...) example to match the current on-chain attestation failure message.
docs/design/attestation-verifier-contract.md	Replaces yield/resume design details with the no-yield promise-chain verifier-contract design and updates source references.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[claude]

Pull request overview

This PR splits the TEE-attestation documentation changes out of the tests-only PR #3715 and rewrites docs/design/attestation-verifier-contract.md to describe the shipped no-yield promise-chain flow (submit_dstack_attestation + resolve_verification, deposit forwarded via .with_attached_deposit, fail_attestation_submission on error) instead of the superseded yield-resume / pending_attestations / 200-block-timeout design. It also updates the re_verify source pointer and repairs stale on-chain error strings in the localnet and TDX external guides. Docs-only change; no code touched.

Changes:

• Rewrite Submission flow, Handling failures, Contract state changes, submit_participant_info API section, and Testing section of docs/design/attestation-verifier-contract.md around the no-yield design
• Update mermaid diagrams to remove promise_yield_create / pending_attestations / on_attestation_verified steps and introduce resolve_verification + fail_attestation_submission receipts
• Add VerificationContext { node_id, attestation } description and drop PendingAttestation, data_id, AttestationResult, and FinalOutcome
• Rename expected_code_hash type in VerifierChangeProposal from CryptoHash to TeeVerifierCodeHash; wrap tee_verifier_account_id in Option<AccountId>, note follow-up Make tee_verifier_account_id non-Option once a verifier is voted in #3639; typedef tee_verifier_votes as TeeVerifierVotes
• Correct re_verify prose reference to crates/mpc-attestation/src/attestation.rs
• Drop the yield-only reference-link definitions (promise-yield-create/resume, enqueue-yield-request, pending-requests-mod, sign-yield-callback, unused metrics/attempts links)
• Trim the two stale contract-panic prefix lines in docs/localnet/tee-localnet.md and docs/running-an-mpc-node-in-tdx-external-guide.md so they match AttestationSubmissionError::InvalidAttestation's current Display

Reviewed changes

Per-file summary

File	Description
docs/design/attestation-verifier-contract.md	Full rewrite of the submission / failure-handling / state / API / testing sections around the no-yield design; drops yield-related state and reference links; updates code snippets, mermaid diagrams, and the VerifierChangeProposal payload type
docs/localnet/tee-localnet.md	Replaces the outdated Invalid TEE Remote Attestation.: TeeQuoteStatus is invalid: ... prefix with the current the submitted attestation failed verification, reason: Custom(...) string emitted by AttestationSubmissionError::InvalidAttestation
docs/running-an-mpc-node-in-tdx-external-guide.md	Same error-string correction in the on-chain panic example

Findings

Spot-checked the shipped implementation against the rewritten prose and code snippets:

• submit_participant_info at crates/contract/src/lib.rs:774 returns Result<PromiseOrValue<()>, Error>, dispatches Mock synchronously and Dstack via submit_dstack_attestation — matches doc.
• submit_dstack_attestation at crates/contract/src/lib.rs:830 returns Err(TeeError::VerifierNotConfigured.into()) when tee_verifier_account_id is None, then chains resolve_verification via .then with .with_attached_deposit(env::attached_deposit()) — matches doc.
• resolve_verification at crates/contract/src/lib.rs:2307 uses #[private] #[payable], maps the three #[callback_result] branches to verify_post_dcap_and_store / QuoteRejected / VerifierUnavailable, and on Err calls refund_to(&account_id, env::attached_deposit()) before scheduling a fail_attestation_submission receipt with .as_return() — matches doc.
• verify_post_dcap_and_store at crates/contract/src/lib.rs:2357 snapshots env::storage_usage(), calls verify_and_store_dstack, then charge_attestation_storage, and on charge failure calls self.tee_state.revert_dstack_store(&context.node_id.tls_public_key, insertion) — matches doc.
• VerificationContext at crates/contract/src/tee/verification_context.rs:11 carries node_id and attestation — matches doc.
• TeeError::{VerifierNotConfigured, QuoteRejected, VerifierUnavailable} at crates/contract/src/errors.rs:35 — matches doc.
• Gas config fields verifier_tera_gas, resolve_verification_tera_gas, fail_attestation_submission_tera_gas at crates/contract/src/config.rs:66-83 — matches doc.
• re_verify at crates/mpc-attestation/src/attestation.rs:217 checks expiry + allowlist invariants (no dcap_qvl::verify call) — matches doc.
• AttestationSubmissionError::InvalidAttestation's #[error(...)] at crates/contract/src/tee/tee_state.rs:42 is "the submitted attestation failed verification, reason: {:?}" — matches the corrected strings in both localnet and TDX guide docs.

No blocking issues found.

Non-blocking (nits):

• docs/design/attestation-verifier-contract.md:570 — the pinned [re-verify] reference-link still points to .../5e47bfe93b3.../crates/mpc-attestation/src/attestation.rs#L93. It's not touched by this PR and remains a stable historical anchor, but the prose reference (line 68) now correctly points to the current file location, so consider re-pinning the reference-link to a commit where re_verify actually lives at the linked line — otherwise the pinned #L93 will drift in meaning as the source moves. Minor.
• docs/design/attestation-verifier-contract.md:405,518 — the draft snippet uses ... and /* tee_upgrade_deadline_duration */ placeholders where the real code passes Duration::from_secs(self.config.tee_upgrade_deadline_duration_seconds). Fine as a draft, just calling out the reader has to infer where the duration comes from.

✅ Approved

[barakeinav1]

Heads-up: #3940 (drop the deposit for submit_participant_info) invalidates part of this rewrite. It's approved and waiting on a re-review, so it will likely land first.

This PR correctly removes the yield-resume drift — the new §Handling failures ("nothing is inserted into contract storage at submit time, so there is no pending entry that a failure could leave wedged") is exactly right. But the rewrite is built on the deposit-forwarding model, which #3940 deletes: submit_participant_info and resolve_verification are no longer #[payable], nothing is forwarded via .with_attached_deposit, and there is no charge or refund. Storage is funded from the contract's own balance.

Symbols this rewrite documents that don't exist on #3940's head:

charge_attestation_storage   0 matches
revert_dstack_store          0 matches
with_attached_deposit        0 matches

Passages that need stripping (line numbers from this PR's version of docs/design/attestation-verifier-contract.md):

• 62 — "The attached deposit is forwarded onto the callback via .with_attached_deposit(...) ... so resolve_verification can charge storage or refund from it directly"
• 64 — "On any error branch resolve_verification refunds the whole attached deposit"
• 79, 91 — the two mermaid labels: "attached deposit forwarded to the callback" and "refund whole attached deposit"
• 103 — "What a failure must still get right is the money — the attached deposit"
• 105 — "resolve_verification is a #[private] #[payable] method"
• 111 — "with any excess deposit refunded inside charge_attestation_storage"
• 115 — "refund_to(&account_id, env::attached_deposit())"
• 120 — the whole verify_post_dcap_and_store commit-order paragraph, which describes charge_attestation_storage / revert_dstack_store / InsufficientDeposit
• 144 — "The attached deposit is not part of it — it rides forward on the promise"
• 384 — "The attached deposit is forwarded onto resolve_verification via .with_attached_deposit"

Line 120 is worth a second look rather than a delete: the underlying observation — that the callback receipt commits even when it returns Err, unlike the synchronous Mock path — is still true and still worth documenting. Only the charge/revert machinery it hangs off is gone.

In the meantime I've added a TODO(#3825) marker over the two stale sections on #3940, so main doesn't silently carry the yield-resume description until this lands. It's one blockquote at the top of §Handling failures — delete it as part of the rewrite.

[claude]

PR title type suggestion: This PR changes editor config, dependencies, and assets alongside documentation, so the type should probably be chore: instead of docs:
Suggested title: chore: align TEE attestation docs and update project files