# How Seismic Works
Seismic adds on-chain privacy to the EVM through three layers: a modified Solidity compiler, a network of TEE-secured nodes, and a shielded storage model. This page explains how they fit together.
## Three pillars
| Layer | What it does |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| **Seismic Solidity compiler** | Adds shielded types (`suint`, `sint`, `sbool`, `sbytes`, `saddress`) that compile to privacy-aware opcodes |
| **Seismic network** | EVM-compatible L1 where nodes run inside Trusted Execution Environments (TEEs) |
| **Shielded storage (FlaggedStorage)** | Storage model where each slot carries an `is_private` flag, enforced at the opcode level |
## The Seismic Solidity compiler
The Seismic compiler (`ssolc`) is a fork of `solc` that understands shielded types. When you write:
```solidity
suint256 balance = 100s;
```
the compiler emits `CSTORE` (opcode `0xB1`) instead of `SSTORE` to write the value, and `CLOAD` (opcode `0xB0`) instead of `SLOAD` to read it. These opcodes tell the EVM to treat the storage slot as private.
The supported shielded types are:
* **`suint`** / **`sint`** -- shielded integers (all standard bit widths: `suint8` through `suint256`)
* **`sbool`** -- shielded boolean
* **`sbytes`** -- shielded bytes, both fixed-length (`sbytes1` through `sbytes32`) and dynamic (`sbytes`)
* **`saddress`** -- shielded address
Arithmetic, comparisons, and assignments work exactly as they do with regular Solidity types. The compiler handles routing to the correct opcodes. You do not need to call any special APIs or change your contract logic.
## The Seismic network
Seismic is an EVM-compatible L1 blockchain. Nodes run inside **Trusted Execution Environments** (TEEs) powered by Intel TDX. The TEE creates a hardware-enforced enclave: code and data inside the enclave cannot be observed or tampered with by the host operating system or the node operator.
Key network properties:
* **Block time:** Sub-second, powered by [Summit](https://github.com/SeismicSystems/summit) (our custom consensus algorithm)
* **Finality:** 1 block
* **Transaction types:** All standard Ethereum types (Legacy, EIP-1559, EIP-2930, EIP-4844, EIP-7702) plus the Seismic transaction type `0x4A`
### The Seismic transaction (type 0x4A)
The diagram below shows the block structure, state tries, and the Seismic transaction format (`TxSeismic`). Note how each storage slot in the Account Storage trie carries a boolean flag -- `(u256, true)` for private slots and `(u256, false)` for public slots.
Standard Ethereum transactions send calldata in plaintext. The Seismic transaction type encrypts calldata before it leaves the user's machine.
The encryption flow:
1. The client calls `seismic_getTeePublicKey` on the RPC to fetch the network's TEE public key.
2. The client performs ECDH key agreement between the user's private key and the TEE public key to derive a shared secret.
3. The calldata is encrypted using AEAD (authenticated encryption with associated data).
4. The encrypted transaction is broadcast to the network.
5. Inside the TEE, the node decrypts the calldata, executes the transaction, and writes results to shielded storage.
At no point is the plaintext calldata visible outside the TEE -- not in the mempool, not in block data, not in transaction traces. For a deeper dive, see [The Seismic Transaction](https://docs.seismic.systems/reference/seismic-transaction).
## Shielded storage (FlaggedStorage)
The diagram below shows how the RPC layer, EVM, and storage interact. Notice that `eth_getStorageAt` is blocked for shielded slots, and cross-contract reads of private storage return zero.
Seismic extends the EVM storage model with **FlaggedStorage**. Each storage slot is a tuple:
```
(value, is_private)
```
When a contract uses `CSTORE` to write a value, the `is_private` flag is set to `true`. This flag has two effects:
* **`eth_getStorageAt` returns zero** for shielded slots, making them indistinguishable from uninitialized storage. External observers cannot read or detect shielded data through the standard RPC.
* **Only `CLOAD` can read private slots.** The standard `SLOAD` opcode cannot access them. This is enforced in the [Seismic EVM](https://github.com/SeismicSystems/seismic-revm).
The compiler manages this automatically. When you declare a variable as `suint256`, the compiler emits `CLOAD`/`CSTORE`. When you declare it as `uint256`, the compiler emits `SLOAD`/`SSTORE`. You do not interact with FlaggedStorage directly.
## End-to-end walkthrough
Here is what happens when a user calls `transfer()` on an SRC20 contract with shielded balances:
```solidity
mapping(address => suint256) balanceOf;
function transfer(address to, suint256 amount) public {
balanceOf[msg.sender] -= amount;
balanceOf[to] += amount;
}
```
**Step 1: User encrypts calldata.** The client library (e.g., `seismic-viem`) fetches the TEE public key, derives a shared secret via ECDH, and encrypts the function and its arguments (`to` and `amount`) using AEAD. The encrypted payload is wrapped in a type `0x4A` transaction.
**Step 2: Transaction enters the mempool.** The calldata is encrypted. Observers can see that a transaction was submitted to the SRC20 contract, but the recipient address and amount are not readable.
**Step 3: Node decrypts inside the TEE.** The Seismic node, running inside Intel TDX, decrypts the calldata using the network's private key. The plaintext arguments are now available only within the enclave.
**Step 4: EVM executes with CSTORE.** The EVM processes the `transfer()` function. Reads from `balanceOf` use `CLOAD`. Writes to `balanceOf` use `CSTORE`. These storage slots will have `is_private = true`.
**Step 5: Storage is updated.** The new balances are written to shielded storage.
**Step 6: Observers see `0x00...0`.** Anyone querying the contract state, reading transaction traces, or inspecting block data sees zero in place of all shielded values -- the balances, the transfer amount, and any intermediate computation involving shielded types.
## Precompiles
Seismic adds six precompiled contracts to the EVM, giving smart contracts access to cryptographic primitives that would be prohibitively expensive to implement in Solidity:
| Address | Name | Purpose |
| ------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `0x64` | [RNG](https://docs.seismic.systems/reference/precompiles/rng) | Securely generate a random number |
| `0x65` | [ECDH](https://docs.seismic.systems/reference/precompiles/ecdh) | Elliptic Curve Diffie-Hellman -- derive a shared secret from a public key and a private key |
| `0x66` | [AES-GCM Encrypt](https://docs.seismic.systems/reference/precompiles/aes-gcm-encrypt) | Encrypt data with AES-GCM |
| `0x67` | [AES-GCM Decrypt](https://docs.seismic.systems/reference/precompiles/aes-gcm-decrypt) | Decrypt data with AES-GCM |
| `0x68` | [HKDF](https://docs.seismic.systems/reference/precompiles/hkdf) | Derive cryptographic keys from a parent key |
| `0x69` | [secp256k1 Sign](https://docs.seismic.systems/reference/precompiles/secp256k1-sign) | Sign a message with a secret key |
These precompiles enable contracts to perform on-chain encryption, key derivation, and random number generation without relying on external oracles or off-chain computation.
## System architecture
The diagram below shows the full Seismic node architecture inside the TEE boundary. Encrypted transactions flow from the client through the RPC layer, into the transaction pool, through consensus, and into the block executor where calldata is decrypted and executed. Shielded results are written to storage.
The system is composed of three components that work together to provide confidential smart contract execution:
| Component | Role |
| ------------------------------------------------------------------ | ------------------------------------------------------------------ |
| [**Seismic Reth**](https://github.com/SeismicSystems/seismic-reth) | Transaction processing, state management, RPC |
| [**Summit**](https://github.com/SeismicSystems/summit) | Consensus and block production |
| **Enclave** | TEE operations: key management, encryption/decryption, attestation |
All three components are designed so that private data is only ever accessible inside the Trusted Execution Environment. No plaintext shielded data leaves the TEE boundary at any point in the pipeline.
### Seismic node
The Seismic node is a fork of [reth](https://github.com/paradigmxyz/reth) (the Rust Ethereum execution client). It handles:
* **RPC**: Accepts incoming transactions and read requests. Serves responses to clients, redacting shielded data from public queries.
* **EVM execution**: Runs a modified EVM that supports `CLOAD`/`CSTORE` opcodes and the six Seismic [precompiles](https://docs.seismic.systems/reference/precompiles). This is built on a forked version of `revm`.
* **State management**: Maintains the world state using FlaggedStorage, where each storage slot is tagged as public or private.
* **Transaction pool**: Receives both standard Ethereum transactions and Seismic transactions. Encrypted calldata in Seismic transactions is decrypted inside the TEE before execution.
The entire node process runs inside an Intel TDX Trusted Execution Environment. This means the node operator cannot inspect memory, attach debuggers, or extract keys from the running process.
### Fork chain
The Seismic execution stack is built on a chain of forks from the Ethereum Rust ecosystem:
```
solidity alloy-core alloy-trie revm revm-inspectors alloy-evm reth foundry compilers foundry-fork-db
| | | | | | | | | |
ssolc seismic- seismic- seismic- seismic-revm- seismic- seismic- seismic- seismic- seismic-
alloy-core trie revm inspectors evm reth foundry compilers foundry-fork-db
```
* [**seismic-alloy-core**](https://github.com/SeismicSystems/seismic-alloy-core) (fork of alloy-core): Shielded types and FlaggedStorage primitives.
* [**seismic-trie**](https://github.com/SeismicSystems/seismic-trie) (fork of alloy-trie): Merkle trie encoding for FlaggedStorage values.
* [**seismic-revm**](https://github.com/SeismicSystems/seismic-revm) (fork of revm): `CLOAD`/`CSTORE` opcodes, Seismic precompiles, and FlaggedStorage access rules.
* [**seismic-revm-inspectors**](https://github.com/SeismicSystems/seismic-revm-inspectors) (fork of revm-inspectors): EVM tracing/debugging with Seismic support.
* [**seismic-evm**](https://github.com/SeismicSystems/seismic-evm) (fork of alloy-evm): Seismic block execution layer.
* [**seismic-reth**](https://github.com/SeismicSystems/seismic-reth) (fork of reth): Full node with Enclave communication, modified RPC (redacting shielded data), and TEE attestation.
* [**seismic-solidity**](https://github.com/SeismicSystems/seismic-solidity) (fork of solidity): Compiler adding shielded types (`suint`, `sbool`, `sbytes`, `saddress`).
* [**seismic-foundry**](https://github.com/SeismicSystems/seismic-foundry) (fork of foundry): `sforge`, `sanvil`, `scast` dev tools.
* [**seismic-compilers**](https://github.com/SeismicSystems/seismic-compilers) (fork of compilers): Compiler integration for sforge.
* [**seismic-foundry-fork-db**](https://github.com/SeismicSystems/seismic-foundry-fork-db) (fork of foundry-fork-db): Fork DB with FlaggedStorage support.
Plus two original repos:
* [**summit**](https://github.com/SeismicSystems/summit): Consensus client.
* [**seismic-enclave**](https://github.com/SeismicSystems/enclave): ECDH + AES-GCM crypto for transaction encryption/decryption.
* [**seismic-alloy**](https://github.com/SeismicSystems/seismic-alloy): Rust SDK with TxSeismic type and encryption-aware providers.
For the full list and dependency flow, see [Repos](https://docs.seismic.systems/reference/repos).
### Summit (consensus)
Summit is Seismic's consensus layer, built on [Commonware](https://github.com/commonwarexyz/monorepo) primitives. It handles:
* **Block production**: Ordering transactions into blocks with sub-second block times.
* **Consensus**: Reaching agreement among validators on the canonical chain.
* **Finality**: Single-block finality -- once a block is produced and agreed upon, it is final.
Summit communicates with the Seismic node to receive transactions from the mempool and to deliver finalized blocks for execution.
### Enclave
The Enclave component manages all TEE-related operations. It is the trust anchor of the system.
**Key management:**
* **Genesis node**: When the network starts, the genesis node generates a root key inside the TEE. This key never leaves the enclave.
* **Peer nodes**: When a new node joins the network, it must pass remote attestation before receiving the root key. The existing nodes verify that the new node is running identical, approved code inside a genuine TEE.
* **Encryption secret key**: The root key is used to derive the network's encryption secret key. This key is used to decrypt the calldata of Seismic transactions (type `0x4A`).
**Attestation:**
Remote attestation is the process by which one TEE proves to another that it is running approved code on genuine hardware. In Seismic:
1. A new node generates an attestation report inside its TEE.
2. The report is sent to existing nodes for verification.
3. Existing nodes check that the report was generated by genuine Intel TDX hardware and that the code measurement matches the approved build.
4. Only after successful verification does the new node receive the root key.
This ensures that every node in the network is running the same software and that no node can be modified to leak private data.
## TEE guarantees
The TEE (Trusted Execution Environment) is the foundation of Seismic's privacy model. Intel TDX provides the following guarantees:
### Code integrity
Remote attestation ensures that all nodes in the network are running identical, approved code. A node cannot be modified to log private data, skip encryption, or export keys.
### Memory isolation
The TEE creates a hardware-enforced boundary around the node's memory. The host operating system, hypervisor, and node operator cannot read or write to the enclave's memory space.
### Key protection
Cryptographic keys (the root key, encryption secret key, and any derived keys) are generated inside the TEE and never leave it. There is no API to export keys from the enclave. Even if the node operator has full root access to the host machine, they cannot extract the keys.
### What TEEs do not protect against
* **Side-channel attacks**: While Intel TDX mitigates many known side-channel attacks, this is an active area of research. Seismic's design minimizes the attack surface, but hardware-level side channels remain a theoretical concern.
* **Bugs in the node software**: If the approved node code has a bug that leaks private data through a public channel (e.g., writing shielded values to public storage), the TEE will faithfully execute that buggy code. This is why the code is open-source and subject to audit.
* **Transaction metadata**: The TEE protects calldata and storage values, but metadata such as sender address, gas usage, and the target contract address remain visible on-chain.
