Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit 9bdb7c7

Browse files
fnerdmanclaude
andcommittedMay 20, 2025·
docs: improve section transitions and wording
- Enhance System Architecture section to better connect with specification - Add explanatory text to Rationale section to frame the content properly - Update wording in TEE Attestation Mechanism to reflect specification context - Improve section references and transitions throughout the document - Add specification context to various components to fit the new structure 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 63b3cf8 commit 9bdb7c7

File tree

1 file changed

+32
-30
lines changed

1 file changed

+32
-30
lines changed
 

‎specs/flashtestations.md

Lines changed: 32 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -12,10 +12,10 @@
1212
- [Flashtestations Protocol Components](#flashtestations-protocol-components)
1313
- [Operational Terms](#operational-terms)
1414
- [Data Structures](#data-structures)
15-
- [TDXQuote](#tdxquote)
16-
- [TDReport](#tdreport)
17-
- [DCAPEndorsements](#dcapendorsements)
18-
- [TDXMeasurements](#tdxmeasurements)
15+
- [**`TDXQuote`**](#tdxquote)
16+
- [**`TDReport`**](#tdreport)
17+
- [**`DCAPEndorsements`**](#dcapendorsements)
18+
- [**`TDXMeasurements`**](#tdxmeasurements)
1919
- [System Architecture](#system-architecture)
2020
- [TEE Attestation Mechanism](#tee-attestation-mechanism)
2121
- [Intel TDX DCAP Attestation](#intel-tdx-dcap-attestation)
@@ -47,7 +47,7 @@
4747
- [Gas Optimization](#gas-optimization)
4848
- [Separation of Concerns](#separation-of-concerns)
4949

50-
## Abstract
50+
# Abstract
5151

5252
Trusted Execution Environments (TEEs) offer a promising approach for running confidential workloads with hardware-enforced security guarantees. However, integrating TEEs with blockchain applications presents significant challenges: How can smart contracts verify that they're interacting with authentic TEE services running expected code? How can this verification scale efficiently onchain? How can we maintain an up-to-date registry of validated services as hardware security requirements evolve?
5353

@@ -58,7 +58,7 @@ Flashtestations addresses these challenges by providing a comprehensive onchain
5858
3. Policy-based authorization for smart contracts to securely interact with TEE services
5959
4. Transparent logging of all attestation events and endorsement changes
6060

61-
## Prerequisites
61+
# Prerequisites
6262

6363
This document assumes familiarity with the following background material, specifications, and tooling. Items are arranged in the rough order they become relevant while reading this spec:
6464

@@ -71,7 +71,7 @@ This document assumes familiarity with the following background material, specif
7171
4. **On‑Chain Endorsement Storage (PCCS)** — Automata’s Solidity implementation that mirrors Intel collateral on Ethereum, enabling fully reproducible verification.
7272
• [Automata On‑chain PCCS](https://github.com/automata-network/automata-on-chain-pccs)
7373

74-
## Motivation
74+
# Motivation
7575

7676
Flashtestations is designed to achieve the following objectives:
7777

@@ -87,11 +87,11 @@ Flashtestations is designed to achieve the following objectives:
8787

8888
6. **Separation of Concerns**: Clearly separate allowlist mechanics from policy governance, enabling independent evolution of these components.
8989

90-
## Specification
90+
# Specification
9191

92-
### System Architecture
92+
## System Architecture
9393

94-
The Flashtestations protocol consists of four key components that work together to provide secure onchain TEE verification:
94+
Within the Flashtestations specification, the protocol architecture consists of four key components that work together to provide secure onchain TEE verification:
9595

9696
```
9797
┌─────────────────────┐ ┌─────────────────────┐
@@ -133,7 +133,7 @@ The Flashtestations protocol consists of four key components that work together
133133
3. **Policy Registry**: Defines which workloads are acceptable for specific onchain interactions
134134
4. **Transparency Log**: Records all attestations and endorsement changes (implemented via events)
135135

136-
### Terminology
136+
## Terminology
137137

138138
The terms in this section are used consistently throughout the specification documents. When a term is first mentioned elsewhere, it links back here.
139139

@@ -197,11 +197,11 @@ The terms in this section are used consistently throughout the specification doc
197197

198198
**Reproducible Build**: A deterministic build process that ensures anyone building the same source code will produce identical binary outputs, enabling verification of expected TEE measurements.
199199

200-
### Data Structures
200+
## Data Structures
201201

202202
The protocol defines several key data structures:
203203

204-
### `TDXQuote`
204+
### **`TDXQuote`**
205205

206206
The output of the Intel TDX attestation process.
207207

@@ -228,7 +228,7 @@ class TDXQuote():
228228
- `UserData`: User-defined data included in the quote (e.g., public key).
229229
- `Signature`: ECDSA signature over the Quote.
230230

231-
### `TDReport`
231+
### **`TDReport`**
232232

233233
Contains the measurement registers and report data from the TEE.
234234

@@ -251,7 +251,7 @@ class TDReport():
251251
- `MROWNER_CONFIG`: Owner-defined configuration.
252252
- `ReportData`: User-defined data included in the report (e.g., public key hash).
253253

254-
### `DCAPEndorsements`
254+
### **`DCAPEndorsements`**
255255

256256
Data provided by Intel to verify the authenticity of a TDX Quote.
257257

@@ -268,7 +268,7 @@ class DCAPEndorsements():
268268
- `TCBInfo`: Trusted Computing Base information.
269269
- `QECertificationData`: Certification data for the attestation key.
270270

271-
### `TDXMeasurements`
271+
### **`TDXMeasurements`**
272272

273273
A structured representation of the TDX measurement registers.
274274

@@ -289,9 +289,9 @@ class TDXMeasurements():
289289
- `MRCONFIGID`: Hash of service configuration stored onchain and fetched on boot.
290290
- `MROWNERCONFIG`: Contains unique instance ID chosen by the operator.
291291

292-
### TEE Attestation Mechanism
292+
## TEE Attestation Mechanism
293293

294-
Attestation is the process by which a TEE proves its identity and integrity. The protocol uses Intel TDX with DCAP (Data Center Attestation Primitives) attestation.
294+
Attestation is the process by which a TEE proves its identity and integrity. This section of the specification defines how the protocol uses Intel TDX with DCAP (Data Center Attestation Primitives) attestation.
295295

296296
### Intel TDX DCAP Attestation
297297

@@ -354,13 +354,13 @@ All of these values are captured in the workload identity hash, ensuring that an
354354

355355
**Note on Reproducible Builds**: To establish trust in expected measurements, TEE workloads must use reproducible build processes where source code, build environment, and instructions are published, allowing independent verification that expected measurements correspond to the published source code.
356356

357-
### Allowlist Registry
357+
## Allowlist Registry
358358

359359
The Allowlist Registry is a core component of Flashtestations that acts as a bookkeeper for tracking which Ethereum addresses have successfully passed attestation within a Trusted Execution Environment (TEE).
360360

361361
### Core Concepts
362362

363-
At its most abstract level, the Allowlist Registry is responsible for:
363+
At its most abstract level within this specification, the Allowlist Registry is responsible for:
364364

365365
1. **Storing addresses** that have been validated through attestation
366366
2. **Associating addresses** with their specific workload identity
@@ -466,7 +466,7 @@ The verification process works as follows:
466466

467467
This approach provides a clean, straightforward way to manage attestation validity over time.
468468

469-
### Policy Layer: Flexible Authorization
469+
## Policy Layer: Flexible Authorization
470470

471471
The Policy layer sits above the Allowlist Registry and provides a more flexible authorization mechanism.
472472

@@ -509,7 +509,7 @@ function isAllowedPolicy(policyId, address) {
509509
}
510510
```
511511

512-
### End-to-End Flow
512+
## End-to-End Flow
513513

514514
The complete verification flow connects attestation, the allowlist, and the policy layer:
515515

@@ -569,7 +569,7 @@ Future optimizations could include:
569569

570570
These optimizations would maintain the design's simplicity while providing more gas-efficient ways to handle endorsement changes, especially as the number of registered addresses grows.
571571

572-
### Offchain TEE Address Verification
572+
## Offchain TEE Address Verification
573573

574574
The Flashtestations protocol enables comprehensive offchain verification of TEE service addresses through its quote storage mechanism. Applications can retrieve the original attestation quote for any registered address via the getQuoteForAddress(address) function, allowing for complete independent verification without incurring gas costs. This approach permits offchain entities to perform the same cryptographic validation as the original onchain verifier, including measurement verification and endorsement checks against the Intel PCS.
575575

@@ -586,7 +586,7 @@ async function verifyTEEAddressOffchain(serviceAddress) {
586586
}
587587
```
588588

589-
### Transparency Log
589+
## Transparency Log
590590

591591
The L2 blockchain functions as a transparency log within Flashtestations, maintaining a permanent record of attestation events and their verification. This log provides auditability, verifiability, and transparency for the entire TEE attestation ecosystem.
592592

@@ -600,7 +600,7 @@ The transparency log serves several critical functions:
600600

601601
### Logged Information
602602

603-
The transparency log captures raw attestation data along with verification results:
603+
As specified in this protocol, the transparency log captures raw attestation data along with verification results:
604604

605605
1. **Raw Attestation Quotes**: The complete DCAP quotes submitted for verification
606606
2. **Intel Endorsements**: The actual endorsement data (endorsements) used to validate attestations
@@ -647,29 +647,31 @@ While the allowlist registry maintains the current authorized state (which addre
647647
1. **Allowlist**: Optimized for efficient runtime checks and state updates
648648
2. **Transparency Log**: Optimized for auditability and historical verification
649649

650-
This dual approach enables efficient onchain operations while maintaining complete transparency and auditability.
650+
This dual approach specified in the protocol enables efficient onchain operations while maintaining complete transparency and auditability.
651651

652-
## Rationale
652+
# Rationale
653+
654+
The following explains the reasoning behind key design decisions in the Flashtestations protocol:
653655

654656
### Replacement Model
655657

656-
The conceptual model uses a direct replacement approach:
658+
The protocol uses a direct replacement approach for attestations:
657659

658660
- When an address re-attests for a workloadId, its old entry is replaced with the new one
659661
- This keeps the model simpler by ensuring each address has exactly one current endorsement per workloadId
660662
- When endorsements become invalid, all addresses using that specific endorsement are removed completely
661663

662664
### Gas Optimization
663665

664-
The system must optimize for gas efficiency, particularly for the lookup operations:
666+
The rationale for gas optimization in the protocol design is that the system must prioritize efficiency, particularly for the lookup operations:
665667

666668
- Lookups should be O(1) regardless of the number of addresses
667669
- Storage slots should be fully cleared when no longer needed (to receive gas refunds)
668670
- Batch operations should be supported for removing addresses when endorsements become invalid
669671

670672
### Separation of Concerns
671673

672-
The design maintains clear separation between:
674+
A key design rationale is maintaining clear separation between:
673675

674676
1. **Allowlist Registry**: Tracks which addresses have attestations validated by current endorsements
675677
2. **Policy Registry**: Defines which workloads are acceptable for specific onchain operations

0 commit comments

Comments
 (0)
Please sign in to comment.