Skip to content

Commit 64ff57b

Browse files
fnerdmanfnerdmanClaude
authored
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]>
1 parent 7644906 commit 64ff57b

File tree

1 file changed

+65
-63
lines changed

1 file changed

+65
-63
lines changed

specs/flashtestations.md

Lines changed: 65 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -1,47 +1,53 @@
11
Flashtestations: Transparent Onchain TEE Verification and Curated Allowlist Protocol
22

3-
## Table of Contents
4-
- [Introduction](#introduction)
5-
- [Design Goals](#design-goals)
6-
- [System Architecture](#system-architecture)
7-
- [Terminology](#terminology)
8-
- [Intel TDX Primitives](#intel-tdx-primitives)
9-
- [Flashtestations Protocol Components](#flashtestations-protocol-components)
10-
- [Operational Terms](#operational-terms)
11-
- [Data Structures](#data-structures)
12-
- [TDXQuote](#tdxquote)
13-
- [TDReport](#tdreport)
14-
- [DCAPEndorsements](#dcapendorsements)
15-
- [TDXMeasurements](#tdxmeasurements)
16-
- [TEE Attestation Mechanism](#tee-attestation-mechanism)
17-
- [Intel TDX DCAP Attestation](#intel-tdx-dcap-attestation)
18-
- [Onchain DCAP Attestation](#onchain-dcap-attestation)
19-
- [Workload Identity Derivation](#workload-identity-derivation)
20-
- [Allowlist Registry](#allowlist-registry)
21-
- [Core Concepts](#core-concepts)
22-
- [Key Relationship Model](#key-relationship-model)
23-
- [Fundamental Operations](#fundamental-operations)
24-
- [Key Requirements](#key-requirements)
25-
- [Policy Layer: Flexible Authorization](#policy-layer-flexible-authorization)
26-
- [Policy Abstraction](#policy-abstraction)
27-
- [Policy Operations](#policy-operations)
28-
- [End-to-End Flow](#end-to-end-flow)
29-
- [Attestation and Registration](#attestation-and-registration)
30-
- [Runtime Authorization](#runtime-authorization)
31-
- [Maintenance: Handling Changing Endorsements](#maintenance-handling-changing-endorsements)
32-
- [Offchain TEE Address Verification](#offchain-tee-address-verification)
33-
- [Transparency Log](#transparency-log)
34-
- [Purpose and Benefits](#purpose-and-benefits)
35-
- [Logged Information](#logged-information)
36-
- [Implementation Approach](#implementation-approach)
37-
- [Relationship with Allowlist](#relationship-with-allowlist)
38-
- [Design Considerations](#design-considerations)
3+
*Authors: [fnerdman](https://github.com/fnerdman), [Melville](https://github.com/Melvillian), [dmarz](https://github.com/dmarzzz), [Ruteri](https://github.com/Ruteri)*
4+
5+
**Table of Contents**
6+
- [Abstract](#abstract)
7+
- [Prerequisites](#prerequisites)
8+
- [Motivation](#motivation)
9+
- [Specification](#specification)
10+
- [Terminology](#terminology)
11+
- [Intel TDX Primitives](#intel-tdx-primitives)
12+
- [Flashtestations Protocol Components](#flashtestations-protocol-components)
13+
- [Operational Terms](#operational-terms)
14+
- [Data Structures](#data-structures)
15+
- [**`TDXQuote`**](#tdxquote)
16+
- [**`TDReport`**](#tdreport)
17+
- [**`DCAPEndorsements`**](#dcapendorsements)
18+
- [**`TDXMeasurements`**](#tdxmeasurements)
19+
- [System Architecture](#system-architecture)
20+
- [TEE Attestation Mechanism](#tee-attestation-mechanism)
21+
- [Intel TDX DCAP Attestation](#intel-tdx-dcap-attestation)
22+
- [Onchain DCAP Attestation](#onchain-dcap-attestation)
23+
- [Workload Identity Derivation](#workload-identity-derivation)
24+
- [Allowlist Registry](#allowlist-registry)
25+
- [Core Concepts](#core-concepts)
26+
- [Key Relationship Model](#key-relationship-model)
27+
- [Fundamental Operations](#fundamental-operations)
28+
- [Key Requirements](#key-requirements)
29+
- [Attestation Verification Endpoint](#attestation-verification-endpoint)
30+
- [Policy Layer: Flexible Authorization](#policy-layer-flexible-authorization)
31+
- [Policy Abstraction](#policy-abstraction)
32+
- [Policy Operations](#policy-operations)
33+
- [End-to-End Flow](#end-to-end-flow)
34+
- [Attestation and Registration](#attestation-and-registration)
35+
- [Runtime Authorization](#runtime-authorization)
36+
- [Maintenance: Handling Changing Endorsements](#maintenance-handling-changing-endorsements)
37+
- [Gas Cost Considerations and Future Optimizations](#gas-cost-considerations-and-future-optimizations)
38+
- [Offchain TEE Address Verification](#offchain-tee-address-verification)
39+
- [Example Verification Flow](#example-verification-flow)
40+
- [Transparency Log](#transparency-log)
41+
- [Purpose and Benefits](#purpose-and-benefits)
42+
- [Logged Information](#logged-information)
43+
- [Implementation Approach](#implementation-approach)
44+
- [Relationship with Allowlist](#relationship-with-allowlist)
45+
- [Rationale](#rationale)
3946
- [Replacement Model](#replacement-model)
4047
- [Gas Optimization](#gas-optimization)
4148
- [Separation of Concerns](#separation-of-concerns)
42-
- [Reproducible Builds](#reproducible-builds)
4349

44-
## Introduction
50+
# Abstract
4551

4652
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?
4753

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

55-
## Prerequisites
61+
# Prerequisites
5662

5763
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:
5864

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

68-
## Design Goals
74+
# Motivation
6975

7076
Flashtestations is designed to achieve the following objectives:
7177

@@ -81,9 +87,11 @@ Flashtestations is designed to achieve the following objectives:
8187

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

90+
# Specification
91+
8492
## System Architecture
8593

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:
8795

8896
```
8997
┌─────────────────────┐ ┌─────────────────────┐
@@ -193,7 +201,7 @@ The terms in this section are used consistently throughout the specification doc
193201

194202
The protocol defines several key data structures:
195203

196-
### `TDXQuote`
204+
### **`TDXQuote`**
197205

198206
The output of the Intel TDX attestation process.
199207

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

223-
### `TDReport`
231+
### **`TDReport`**
224232

225233
Contains the measurement registers and report data from the TEE.
226234

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

246-
### `DCAPEndorsements`
254+
### **`DCAPEndorsements`**
247255

248256
Data provided by Intel to verify the authenticity of a TDX Quote.
249257

@@ -260,7 +268,7 @@ class DCAPEndorsements():
260268
- `TCBInfo`: Trusted Computing Base information.
261269
- `QECertificationData`: Certification data for the attestation key.
262270

263-
### `TDXMeasurements`
271+
### **`TDXMeasurements`**
264272

265273
A structured representation of the TDX measurement registers.
266274

@@ -283,7 +291,7 @@ class TDXMeasurements():
283291

284292
## TEE Attestation Mechanism
285293

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.
287295

288296
### Intel TDX DCAP Attestation
289297

@@ -344,13 +352,15 @@ These measurement registers serve specific purposes in the permissioned attestat
344352

345353
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.
346354

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+
347357
## Allowlist Registry
348358

349359
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).
350360

351361
### Core Concepts
352362

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:
354364

355365
1. **Storing addresses** that have been validated through attestation
356366
2. **Associating addresses** with their specific workload identity
@@ -590,7 +600,7 @@ The transparency log serves several critical functions:
590600

591601
### Logged Information
592602

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:
594604

595605
1. **Raw Attestation Quotes**: The complete DCAP quotes submitted for verification
596606
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
637647
1. **Allowlist**: Optimized for efficient runtime checks and state updates
638648
2. **Transparency Log**: Optimized for auditability and historical verification
639649

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
641653

642-
## Design Considerations
654+
The following explains the reasoning behind key design decisions in the Flashtestations protocol:
643655

644656
### Replacement Model
645657

646-
The conceptual model uses a direct replacement approach:
658+
The protocol uses a direct replacement approach for attestations:
647659

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

652664
### Gas Optimization
653665

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:
655667

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

660672
### Separation of Concerns
661673

662-
The design maintains clear separation between:
674+
A key design rationale is maintaining clear separation between:
663675

664676
1. **Allowlist Registry**: Tracks which addresses have attestations validated by current endorsements
665677
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
670682

671683
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.
672684

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

Comments
 (0)