Flashtestations

A protocol for allowing any TDX device to prove its output onchain

Its first use case will be for proving that blocks on the Unichain L2 were built using fair and transparent ordering rules

System Components

1. TEE Devices
2. TEE Public Keys (these are used to identify and verify TEEs and their outputs)
3. TEE Attestations (also called Quotes)
4. Block Signature Transaction
5. Governance Values

System Flows

1. Registering a TEE Device (also referred to as a block builder)

   a. Should only be callable from a TEE-controlled address

   b. Verify TEE Quote

   c. extract and store TEE address and workload info

   d. set liveness (we want a way to indicate that a TEE device has not been active for a long period of time, and for that we use liveness)

2. Verify Flashtestation transaction

   a. Check signature of transactions against registry of live builder keys

   b. update TEE device liveness

3. Deregistering a TEE Device

   b. Mark TEE device as "retired"

Deploy

Before deploying anything, create your own .env file:

# fill in the necessary values for your .env. If confused, you can reference
# https://getfoundry.sh/guides/scripting-with-solidity
# to see what the values mean
cp env.sample .env

source .env

Then, provide correct values for the following env vars, which all the forge scripts below will use:

• ETHERSCAN_API_KEY
• UNICHAIN_SEPOLIA_RPC_URL

Unichain Sepolia

FlashtestationsRegistry

This is the primary contract of this repository. It allows TDX v4 devices to register themselves onchain with an Ethereum address/public key, such that later transactions from that address can be trusted to originate from a TEE.

Before deploying provide correct values for the following env vars:

# you can find the deployed values here: https://github.com/automata-network/automata-dcap-attestation?tab=readme-ov-file#testnet
AUTOMATA_DCAP_ATTESTATION_FEE_ADDRESS=0x0000000000000000000000000000000000000042

# this is the contract that can upgrade the registry's code
FLASHTESTATION_REGISTRY_OWNER=0x0000000000000000000000000000000000000042

Then, to deploy, run:

source .env

forge script --chain 1301 script/FlashtestationRegistry.s.sol:FlashtestationRegistryScript --rpc-url $UNICHAIN_SEPOLIA_RPC_URL --broadcast --verify --interactives 1 -vvvv

BlockBuilderPolicy

A simple contract that allows your organization (e.g. Flashbots) to permission TEE's and their registered Ethereum addresses + workloadIds

Before deploying provide correct values for the following env vars:

# this is the contract FlashtestationRegistry you deployed up above
FLASHTESTATION_REGISTRY_ADDRESS=0x0000000000000000000000000000000000000042

# this is the contract that can upgrade the policy's code
OWNER_BLOCK_BUILDER_POLICY=0x0000000000000000000000000000000000000042

Then, to deploy, run:

source .env

forge script --chain 1301 script/BlockBuilderPolicy.s.sol:BlockBuilderPolicyScript --rpc-url $UNICHAIN_SEPOLIA_RPC_URL --broadcast --verify --interactives 1 -vvvv

Interactions

RegisterTEEScript

This registers a TEE-controlled address using a quote generated by a v4 TDX device

Before executing this script, provide correct values for the following env vars:

# this is the contract FlashtestationRegistry you deployed up above
FLASHTESTATION_REGISTRY_ADDRESS=0x0000000000000000000000000000000000000042

# this is an absolute path to the raw attestation quote, see the example at: script/raw_tdx_quotes/342ad26adb6185cda1aea67ee5f35e9cb5c9cec32b03e8d4382492ca35d53331e906b20edbe46d9337b7b2b2248c633cc2a3aeb3a0ce480dd22b5950860c8a2c
PATH_TO_ATTESTATION_QUOTE=/some/path/quote.bin

Then, to execute, run:

source .env

# Note: we pass '--skip-simulation' because of a bug where the forge EVM does not contain the precompiles necessary
# to execute the FlashtestationRegistry.registerTEEService, and so we need to skip simulating it locally
#
# Note: we need to use a RPC provider like Alchemy for the $UNICHAIN_SEPOLIA_RPC_URL argument, and we can't
# use https://sepolia.unichain.org, because this script makes so many gas-heavy calls that it will last
# longer than 128 blocks worth of time, at which point the full nodes at sepolia.unichain.org will start
# to return errors. We must use RPC provider like Alchemy because they can service calls to archive nodes,
# which get around this problem.
forge script --chain 1301 script/Interactions.s.sol:RegisterTEEScript --rpc-url $UNICHAIN_SEPOLIA_RPC_URL --broadcast --verify --interactives 1 -vvvv --skip-simulation

AddWorkloadToPolicyScript

Add a workloadId that was previously registered with the RegisterTEEScript script above

Before executing this script, provide correct values for the following env vars:

# this is the contract BlockBuilderPolicy you deployed up above
ADDRESS_BLOCK_BUILDER_POLICY=0x0000000000000000000000000000000000000042

# this is the workload ID emitted in the event from the RegisterTEEScript up above
WORKLOAD_ID=0xeee********************************************************9164e

Then, to execute, run:

source .env

forge script --chain 1301 script/Interactions.s.sol:AddWorkloadToPolicyScript --rpc-url $UNICHAIN_SEPOLIA_RPC_URL --broadcast --verify --interactives 1 -vvvv