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
Restructure and restyle flashtestations to look more like flashblocks spec (#240)
* feat: simplify allowlist registry by removing tcbHash tracking
- Remove tcbHash tracking and endorsement bundle references
- Simplify registration to store quotes directly with addresses
- Add per-attestation verification endpoint for checking validity
- Update maintenance approach to mark outdated attestations individually
- Add gas cost considerations for future optimizations
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <[email protected]>
* docs: restructure flashtestations doc format
- Rename "Introduction" to "Abstract"
- Rename "Design Goals" to "Motivation"
- Add new "Specification" section as parent for technical content
- Make technical sections H3 headings under Specification
- Rename "Design Considerations" to "Rationale"
- Add "Implementation" section and move "Reproducible Builds" under it
- Update Table of Contents to reflect new structure
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <[email protected]>
* docs: add authors and remove implementation section
- Add authors list at the top of the document
- Format Table of Contents to match flashblocks style
- Remove Implementation section
- Add condensed note about reproducible builds to Workload Identity section
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <[email protected]>
* 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 <[email protected]>
---------
Co-authored-by: fnerdman <[email protected]>
Co-authored-by: Claude <[email protected]>
-[Relationship with Allowlist](#relationship-with-allowlist)
45
+
-[Rationale](#rationale)
39
46
-[Replacement Model](#replacement-model)
40
47
-[Gas Optimization](#gas-optimization)
41
48
-[Separation of Concerns](#separation-of-concerns)
42
-
-[Reproducible Builds](#reproducible-builds)
43
49
44
-
## Introduction
50
+
#Abstract
45
51
46
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?
47
53
@@ -52,7 +58,7 @@ Flashtestations addresses these challenges by providing a comprehensive onchain
52
58
3. Policy-based authorization for smart contracts to securely interact with TEE services
53
59
4. Transparent logging of all attestation events and endorsement changes
54
60
55
-
##Prerequisites
61
+
# Prerequisites
56
62
57
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:
58
64
@@ -65,7 +71,7 @@ This document assumes familiarity with the following background material, specif
65
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:
71
77
@@ -81,9 +87,11 @@ Flashtestations is designed to achieve the following objectives:
81
87
82
88
6.**Separation of Concerns**: Clearly separate allowlist mechanics from policy governance, enabling independent evolution of these components.
83
89
90
+
# Specification
91
+
84
92
## System Architecture
85
93
86
-
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:
87
95
88
96
```
89
97
┌─────────────────────┐ ┌─────────────────────┐
@@ -193,7 +201,7 @@ The terms in this section are used consistently throughout the specification doc
193
201
194
202
The protocol defines several key data structures:
195
203
196
-
### `TDXQuote`
204
+
### **`TDXQuote`**
197
205
198
206
The output of the Intel TDX attestation process.
199
207
@@ -220,7 +228,7 @@ class TDXQuote():
220
228
-`UserData`: User-defined data included in the quote (e.g., public key).
221
229
-`Signature`: ECDSA signature over the Quote.
222
230
223
-
### `TDReport`
231
+
### **`TDReport`**
224
232
225
233
Contains the measurement registers and report data from the TEE.
226
234
@@ -243,7 +251,7 @@ class TDReport():
243
251
-`MROWNER_CONFIG`: Owner-defined configuration.
244
252
-`ReportData`: User-defined data included in the report (e.g., public key hash).
245
253
246
-
### `DCAPEndorsements`
254
+
### **`DCAPEndorsements`**
247
255
248
256
Data provided by Intel to verify the authenticity of a TDX Quote.
249
257
@@ -260,7 +268,7 @@ class DCAPEndorsements():
260
268
-`TCBInfo`: Trusted Computing Base information.
261
269
-`QECertificationData`: Certification data for the attestation key.
262
270
263
-
### `TDXMeasurements`
271
+
### **`TDXMeasurements`**
264
272
265
273
A structured representation of the TDX measurement registers.
266
274
@@ -283,7 +291,7 @@ class TDXMeasurements():
283
291
284
292
## TEE Attestation Mechanism
285
293
286
-
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.
287
295
288
296
### Intel TDX DCAP Attestation
289
297
@@ -344,13 +352,15 @@ These measurement registers serve specific purposes in the permissioned attestat
344
352
345
353
All of these values are captured in the workload identity hash, ensuring that any change to the code, configuration, or operator results in a different identity that must be explicitly authorized through governance.
346
354
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
+
347
357
## Allowlist Registry
348
358
349
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).
350
360
351
361
### Core Concepts
352
362
353
-
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:
354
364
355
365
1.**Storing addresses** that have been validated through attestation
356
366
2.**Associating addresses** with their specific workload identity
@@ -590,7 +600,7 @@ The transparency log serves several critical functions:
590
600
591
601
### Logged Information
592
602
593
-
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:
594
604
595
605
1.**Raw Attestation Quotes**: The complete DCAP quotes submitted for verification
596
606
2.**Intel Endorsements**: The actual endorsement data (endorsements) used to validate attestations
@@ -637,29 +647,31 @@ While the allowlist registry maintains the current authorized state (which addre
637
647
1.**Allowlist**: Optimized for efficient runtime checks and state updates
638
648
2.**Transparency Log**: Optimized for auditability and historical verification
639
649
640
-
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
+
652
+
# Rationale
641
653
642
-
## Design Considerations
654
+
The following explains the reasoning behind key design decisions in the Flashtestations protocol:
643
655
644
656
### Replacement Model
645
657
646
-
The conceptual model uses a direct replacement approach:
658
+
The protocol uses a direct replacement approach for attestations:
647
659
648
660
- When an address re-attests for a workloadId, its old entry is replaced with the new one
649
661
- This keeps the model simpler by ensuring each address has exactly one current endorsement per workloadId
650
662
- When endorsements become invalid, all addresses using that specific endorsement are removed completely
651
663
652
664
### Gas Optimization
653
665
654
-
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:
655
667
656
668
- Lookups should be O(1) regardless of the number of addresses
657
669
- Storage slots should be fully cleared when no longer needed (to receive gas refunds)
658
670
- Batch operations should be supported for removing addresses when endorsements become invalid
659
671
660
672
### Separation of Concerns
661
673
662
-
The design maintains clear separation between:
674
+
A key design rationale is maintaining clear separation between:
663
675
664
676
1.**Allowlist Registry**: Tracks which addresses have attestations validated by current endorsements
665
677
2.**Policy Registry**: Defines which workloads are acceptable for specific onchain operations
@@ -670,13 +682,3 @@ This separation enables each component to evolve independently, with governance
670
682
671
683
The Allowlist Registry also provides direct access to stored attestation quotes, allowing external systems to perform their own verification or analysis without requiring additional onchain transactions.
672
684
673
-
## Reproducible Builds
674
-
675
-
To establish trust in expected measurements, the TEE block builder must be built using a reproducible build process:
676
-
677
-
1.**Source Code Publication**: The full source code is published with a specific commit hash
678
-
2.**Build Environment**: A deterministic build environment is defined (specific compiler versions, dependencies, etc.)
679
-
3.**Build Instructions**: Step-by-step instructions to reproduce the build are published
680
-
4.**Verification**: Independent parties can follow the build process and verify that it produces the same measurements
681
-
682
-
This allows anyone to verify that the expected measurements correspond to the published source code.
0 commit comments