You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
- 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>
-[Separation of Concerns](#separation-of-concerns)
49
49
50
-
##Abstract
50
+
# Abstract
51
51
52
52
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?
53
53
@@ -58,7 +58,7 @@ Flashtestations addresses these challenges by providing a comprehensive onchain
58
58
3. Policy-based authorization for smart contracts to securely interact with TEE services
59
59
4. Transparent logging of all attestation events and endorsement changes
60
60
61
-
##Prerequisites
61
+
# Prerequisites
62
62
63
63
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:
64
64
@@ -71,7 +71,7 @@ This document assumes familiarity with the following background material, specif
71
71
4.**On‑Chain Endorsement Storage (PCCS)** — Automata’s Solidity implementation that mirrors Intel collateral on Ethereum, enabling fully reproducible verification.
Flashtestations is designed to achieve the following objectives:
77
77
@@ -87,11 +87,11 @@ Flashtestations is designed to achieve the following objectives:
87
87
88
88
6.**Separation of Concerns**: Clearly separate allowlist mechanics from policy governance, enabling independent evolution of these components.
89
89
90
-
##Specification
90
+
# Specification
91
91
92
-
###System Architecture
92
+
## System Architecture
93
93
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:
95
95
96
96
```
97
97
┌─────────────────────┐ ┌─────────────────────┐
@@ -133,7 +133,7 @@ The Flashtestations protocol consists of four key components that work together
133
133
3.**Policy Registry**: Defines which workloads are acceptable for specific onchain interactions
134
134
4.**Transparency Log**: Records all attestations and endorsement changes (implemented via events)
135
135
136
-
###Terminology
136
+
## Terminology
137
137
138
138
The terms in this section are used consistently throughout the specification documents. When a term is first mentioned elsewhere, it links back here.
139
139
@@ -197,11 +197,11 @@ The terms in this section are used consistently throughout the specification doc
197
197
198
198
**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.
199
199
200
-
###Data Structures
200
+
## Data Structures
201
201
202
202
The protocol defines several key data structures:
203
203
204
-
### `TDXQuote`
204
+
### **`TDXQuote`**
205
205
206
206
The output of the Intel TDX attestation process.
207
207
@@ -228,7 +228,7 @@ class TDXQuote():
228
228
-`UserData`: User-defined data included in the quote (e.g., public key).
229
229
-`Signature`: ECDSA signature over the Quote.
230
230
231
-
### `TDReport`
231
+
### **`TDReport`**
232
232
233
233
Contains the measurement registers and report data from the TEE.
234
234
@@ -251,7 +251,7 @@ class TDReport():
251
251
-`MROWNER_CONFIG`: Owner-defined configuration.
252
252
-`ReportData`: User-defined data included in the report (e.g., public key hash).
253
253
254
-
### `DCAPEndorsements`
254
+
### **`DCAPEndorsements`**
255
255
256
256
Data provided by Intel to verify the authenticity of a TDX Quote.
257
257
@@ -268,7 +268,7 @@ class DCAPEndorsements():
268
268
-`TCBInfo`: Trusted Computing Base information.
269
269
-`QECertificationData`: Certification data for the attestation key.
270
270
271
-
### `TDXMeasurements`
271
+
### **`TDXMeasurements`**
272
272
273
273
A structured representation of the TDX measurement registers.
274
274
@@ -289,9 +289,9 @@ class TDXMeasurements():
289
289
-`MRCONFIGID`: Hash of service configuration stored onchain and fetched on boot.
290
290
-`MROWNERCONFIG`: Contains unique instance ID chosen by the operator.
291
291
292
-
###TEE Attestation Mechanism
292
+
## TEE Attestation Mechanism
293
293
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.
295
295
296
296
### Intel TDX DCAP Attestation
297
297
@@ -354,13 +354,13 @@ All of these values are captured in the workload identity hash, ensuring that an
354
354
355
355
**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.
356
356
357
-
###Allowlist Registry
357
+
## Allowlist Registry
358
358
359
359
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).
360
360
361
361
### Core Concepts
362
362
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:
364
364
365
365
1.**Storing addresses** that have been validated through attestation
366
366
2.**Associating addresses** with their specific workload identity
@@ -466,7 +466,7 @@ The verification process works as follows:
466
466
467
467
This approach provides a clean, straightforward way to manage attestation validity over time.
468
468
469
-
###Policy Layer: Flexible Authorization
469
+
## Policy Layer: Flexible Authorization
470
470
471
471
The Policy layer sits above the Allowlist Registry and provides a more flexible authorization mechanism.
472
472
@@ -509,7 +509,7 @@ function isAllowedPolicy(policyId, address) {
509
509
}
510
510
```
511
511
512
-
###End-to-End Flow
512
+
## End-to-End Flow
513
513
514
514
The complete verification flow connects attestation, the allowlist, and the policy layer:
515
515
@@ -569,7 +569,7 @@ Future optimizations could include:
569
569
570
570
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.
571
571
572
-
###Offchain TEE Address Verification
572
+
## Offchain TEE Address Verification
573
573
574
574
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.
575
575
@@ -586,7 +586,7 @@ async function verifyTEEAddressOffchain(serviceAddress) {
586
586
}
587
587
```
588
588
589
-
###Transparency Log
589
+
## Transparency Log
590
590
591
591
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.
592
592
@@ -600,7 +600,7 @@ The transparency log serves several critical functions:
600
600
601
601
### Logged Information
602
602
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:
604
604
605
605
1.**Raw Attestation Quotes**: The complete DCAP quotes submitted for verification
606
606
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
647
647
1.**Allowlist**: Optimized for efficient runtime checks and state updates
648
648
2.**Transparency Log**: Optimized for auditability and historical verification
649
649
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.
651
651
652
-
## Rationale
652
+
# Rationale
653
+
654
+
The following explains the reasoning behind key design decisions in the Flashtestations protocol:
653
655
654
656
### Replacement Model
655
657
656
-
The conceptual model uses a direct replacement approach:
658
+
The protocol uses a direct replacement approach for attestations:
657
659
658
660
- When an address re-attests for a workloadId, its old entry is replaced with the new one
659
661
- This keeps the model simpler by ensuring each address has exactly one current endorsement per workloadId
660
662
- When endorsements become invalid, all addresses using that specific endorsement are removed completely
661
663
662
664
### Gas Optimization
663
665
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:
665
667
666
668
- Lookups should be O(1) regardless of the number of addresses
667
669
- Storage slots should be fully cleared when no longer needed (to receive gas refunds)
668
670
- Batch operations should be supported for removing addresses when endorsements become invalid
669
671
670
672
### Separation of Concerns
671
673
672
-
The design maintains clear separation between:
674
+
A key design rationale is maintaining clear separation between:
673
675
674
676
1.**Allowlist Registry**: Tracks which addresses have attestations validated by current endorsements
675
677
2.**Policy Registry**: Defines which workloads are acceptable for specific onchain operations
0 commit comments