1 of 100

General

Overview

Welcome

Private by Default. Familiar by Design.

Seismic is an EVM blockchain with native on-chain privacy. Write Solidity. Deploy with Foundry. Interact with Viem. The only difference: your users' data stays private.

One letter changes everything

The difference between a public ERC20 and a private SRC20 is one letter:

The s prefix tells the Seismic compiler to shield the underlying value. Observers see

Why Seismic

As shown on the welcome page, shielding a Solidity contract can be as simple as adding an s prefix to your types. But why does that matter?

The transparency problem

Blockchains are public ledgers. Every balance, every transaction, every contract interaction is visible to anyone with a block explorer. This transparency was a design choice -- but it creates real problems:

Front-running and MEV extraction. Bots watch the mempool, see your trade, and sandwich it for profit. On Ethereum, MEV extraction costs users billions annually.
Competitive intelligence leaks. If your protocol holds assets on-chain, competitors can see your treasury, your positions, and your strategy in real time.
Privacy violations for end users. When Alice sends tokens to Bob, everyone can see how much she holds, how much she sent, and build a complete transaction graph linking her activity.
Business logic exposure. Contract state is fully readable. Pricing algorithms, liquidation thresholds, and internal parameters are all public.

Traditional finance operates with confidentiality by default. Public blockchains flip that assumption, and it limits what you can build.

Why existing privacy solutions fall short

Several projects have tried to solve this. None of them let you stay in Solidity.

Approach

Limitation

Each of these approaches forces a tradeoff: learn a new language, accept limited functionality, or live with performance constraints.

The Seismic approach

Seismic solves on-chain privacy with two innovations working together:

Shielded types in the compiler

Seismic extends the Solidity compiler with shielded types: suint, sint, sbool, sbytes, and saddress. The s prefix marks a value as shielded. Under the hood, these compile to CLOAD and CSTORE opcodes (instead of the standard SLOAD/SSTORE), which route data through shielded storage.

No new language. No new programming model. Just a one-letter prefix on the types you already know.

TEE-based execution

Seismic nodes run inside Trusted Execution Environments (TEEs) using Intel TDX. The TEE creates a hardware-enforced boundary: even the node operator cannot read the data being processed. Transactions are encrypted before they hit the network and decrypted only inside the TEE for execution.

Together, these two layers provide privacy at the language level and enforcement at the hardware level.

What does not change

Seismic is designed so that everything around the privacy layer stays familiar:

Same language. Standard Solidity, with shielded types added. No new syntax beyond the s prefix. Existing Solidity contracts compile and deploy without modification.
Same tooling. sforge, sanvil, and ssolc are forks of Foundry's forge, anvil

Getting Started

Installation

Setting up your local machine to develop with Seismic

System requirements

Before you begin, make sure your machine meets the following requirements:

x86_64 or arm64 architecture

Quickstart

You're two commands away from running an encrypted protocol

You can play around with shielded types using our starter repository. This assumes you went through everything in Installation.

git clone "https://github.com/SeismicSystems/seismic-starter.git"
cd seismic-starter/packages/contracts
sforge test -vv

Or if you prefer a more detailed walkthrough of building on Seismic, check out our Tutorials section.

Web Interface

Deploy SRC20 tokens from a browser using the SRC20 Factory web interface

The SRC20 Factory ships a React web GUI (packages/web) for deploying tokens directly from a browser wallet, no CLI or code required.

Running the web app

Clone the repo and start the dev server:

REST API

Query SRC20 tokens deployed through the factory via a REST API

The src20-factory repo includes a Rust API server (Axum) that reads factory and token state over HTTP. It is useful for indexing deployed tokens or fetching token metadata from non-TypeScript environments.

Running the server

cd packages/api
cargo run

The server starts on port 3001 and connects to Seismic testnet at https://testnet-2.seismictest.net/rpc.

GET /api/tokens

Returns all tokens ever deployed through the factory, with their metadata.

Request

Response

Addresses are returned as lowercase hex, not EIP-55 checksummed.

Note that total_supply is always in base units (not scaled by decimals).

GET /api/token/{address}

Returns metadata for a single token by address.

Request

Response

Error response

If the address is invalid or the RPC call fails, the server returns a JSON error:

What the API can and cannot read

The API uses a standard public provider — it does not hold a private key. This means it can read public state like name, symbol, decimals, owner, and totalSupply, but it cannot read shielded state like individual balances or allowances, which require a signed read from the balance holder. See for how those work.

Tutorials

SRC20: Private Token

\Build a private ERC20 token where balances and transfers are hidden from observers

In this tutorial, you will build a fully functional private ERC20 token -- an SRC20 -- where balances, transfer amounts, and allowances are all shielded from external observers. Anyone watching the chain sees 0x00...0 instead of actual values, yet the token behaves like a standard ERC20 from the user's perspective.

What you'll build

By the end of this tutorial you will have:

An SRC20 smart contract with shielded balances, transfers, and allowances
Encrypted transfer events that only the sender and recipient can decrypt
A signed-read pattern that lets users check their own balance without anyone else knowing it
Compliance-ready access control through Intelligence Contracts
A React frontend that connects everything end-to-end

What makes this special

The contract changes from a standard ERC20 to an SRC20 are remarkably small. The core of it is changing uint256 to suint256 for balances, amounts, and allowances. The transfer logic, require checks, and overall structure stay almost identical. Seismic's compiler handles the rest -- routing reads and writes through shielded storage automatically.

This is the power of Seismic's approach: privacy is a type-level annotation, not a protocol-level rewrite.

Prerequisites

Before starting, make sure you have:

Seismic development tools installed -- sforge, sanvil, and ssolc. See the if you have not set these up yet.
Solidity familiarity -- You should be comfortable writing and reading Solidity contracts.

What you'll learn

Chapter

Topic

Key concept

Tutorial structure

Chapter 1 starts with a side-by-side comparison of a standard ERC20 and the SRC20 version, walking through every changed line. Chapter 2 dives into the implementation of shielded transfers, allowances, and minting, including how to test with sforge. Chapter 3 tackles encrypted events -- since shielded types cannot appear in event parameters, you will use AES-GCM precompiles to encrypt sensitive data before emitting. Chapter 4 introduces signed reads, the mechanism that lets users query their own balance without exposing it. Chapter 5 adds compliance through Intelligence Contracts, showing how authorized roles can inspect shielded state. Chapter 6 brings it all together with a React frontend using seismic-react.

Each chapter builds on the previous one. By the end, you will have a complete, deployable private token with a working frontend.

Verify devtool installation

Before continuing, ensure that you have completed the steps in the Installation section to install all necessary Seismic developer tools:

sforge: Framework for testing and deploying smart contracts.
sanvil: Local Seismic node.
ssolc: The Seismic Solidity compiler.

Run each of the above commands in your terminal with a --version flag to ensure that they're installed correctly.

Also ensure that you have installed on your machine. If you do not have bun installed, follow the instructions to install it on your machine.

Create project structure

Create the project folder and navigate into it:

Create the packages directory with subdirectories for contracts and cli

Initialize contracts

Navigate to the contracts subdirectory:

Initialize a project with sforge:

This command will:

Initialize the CLI

Now that the contracts subdirectory has been initialized, you should now initialize the cli subdirectory that will be used to interact with the deployed contracts.

Navigate to the CLI subdirectory:

Initialize a new bun project

Writing the Contract

This section dives into the heart of Clown Beatdown — the shielded smart contract that powers its functionality. You'll start by building the secrets pool using shielded storage, then implement the stamina system and the robbery mechanic, before adding rounds, resets, and contributor-based access control. By the end of this section, you'll have a fully functional, round-based ClownBeatdown contract that is secure, fair, and replayable.

What You'll Learn

In this section, you'll:

Ch 1: The Secrets Pool

In this chapter, you'll learn to create and initialize the secrets pool — a collection of hidden strings stored inside the clown's pockets — and implement a function to add new secrets. Estimated time: ~10 minutes.

Defining the secrets pool

The secrets pool is the collection of hidden strings that the clown carries. Using Seismic's sbytes type, each secret is shielded on-chain — encrypted and invisible to observers. A shielded suint256 index determines which secret gets revealed when the clown is robbed. Open up

Seismic-viem Primer

Before proceeding to write the CLI, you need to be acquainted with some of the functions and utilities used to enable Seismic primitives (e.g. shielded reads, shielded writes etc.) through our client library, seismic-viem, which we will be using heavily to write the CLI. The detailed docs for seismic-viem can be found here. Estimated time: ~15 minutes

Shielded wallet client

The shielded wallet client is the shielded/Seismic counterpart of the wallet client in viem. It is used to enable extended functionality for interacting with shielded blockchain features, wallet operations, and encryption. It can be initialized using the createShieldedWalletClient function as follows:

createShieldedWalletClient takes in the following parameters:

chain: a well-defined object
transport: the method of transport of interacting with the chain (http/ws along with the corresponding RPC URL)

Once initialized, it can then be used to perform wallet operations or shielded-specific actions.

Shielded contract

A shielded contract instance provides an interface to interact with a shielded contract onchain. It has extended functionality for performing shielded write operations, signed reads, and contract interaction for a specific contract performed by a specific wallet client that it is initialized with. It can be initialized with getShieldedContract as follows:

It takes in the following parameters:

abi: the ABI of the contract it is interacting with.
address: the address of the deployed contract it is interacting with.
client: the shielded wallet client that the interactions are to be performed by.

This function extends the base getContract functionality by adding:

Shielded write actions for nonpayable and payable functions.
Signed read actions for pure and view functions.

We will extensively use shielded writes (for addSecret) and signed reads (for rob()) in our CLI.

Building the Frontend

In this section, you'll build a React frontend for the Clown Beatdown game. Players connect their wallet, punch the clown to reduce its stamina, and rob a shielded secret once it's knocked out — all from the browser. Estimated time: ~45 minutes

The frontend uses seismic-react to integrate shielded wallet functionality with a standard React + wagmi + RainbowKit stack. By the end of this section, you'll have a fully playable web app running against your local Seismic node.

What You'll Learn

Set up a React + Vite project with seismic-react, wagmi, and RainbowKit
Configure providers for shielded wallet support
Build custom hooks to interact with the ClownBeatdown contract
Create game UI components with animations and responsive layout

Overview of Chapters

Install dependencies, configure Vite, and wire up the provider stack: WagmiProvider, RainbowKitProvider, and ShieldedWalletProvider from seismic-react.

Build the hooks that connect your UI to the ClownBeatdown contract — useContract, useContractClient, and useGameActions.

Create the game interface: the clown sprite with punch animations, action buttons (hit, rob, reset), and the entry screen with wallet connection.

Seismic Solidity

Collections

Using stype variables in arrays and maps

Shielded Arrays

Arrays of shielded types work like standard Solidity arrays. Keys (indices) must be non-shielded — using a shielded type as an array index is a compiler error.

They come in two forms:

Dynamic (suint256[], sbool[], saddress[], etc.) — the length is stored as shielded.
Fixed-size (suint256[5], sbool[4], saddress[3], etc.) — the length is a compile-time constant and publicly visible.

Even with dynamic shielded arrays, an upper bound on the length may be visible to observers monitoring gas costs, since gas usage scales with array operations.

Shielded Mappings

Mappings can have shielded values but keys cannot be shielded types. Using a shielded type as a mapping key is a compiler error. The standard mapping syntax applies.

Best Practices

These are guidelines for writing secure Seismic contracts. Following them will help you avoid the most common privacy mistakes.

Always Use Seismic Transactions for Shielded Parameters

Any function that accepts shielded types as parameters should be called using a Seismic transaction (type 0x4A), which encrypts the calldata. If calldata is not encrypted, the shielded parameter values are visible in plaintext in the transaction's input data, defeating the purpose of using shielded types. This applies to all function calls that pass shielded values as parameters.

Clients

Overview

Seismic maintains client libraries for three languages.

TypeScript

seismic-viem

composes with to add Seismic transaction support, encrypted calldata, and signed reads. See the .

seismic-react

composes with to provide React hooks for shielded reads, writes, and wallet management. See the .

Python — seismic-web3

composes with to interact with Seismic nodes from Python. See the .

Rust — seismic-alloy

composes with to provide Seismic transaction types and encryption-aware providers. See the .

The docs for all three of these libraries are pure AI slop. The Python docs have been manually reviewed and cleaned up; we're auditing the TypeScript and Rust docs shortly. Refer to the source code if anything seems off.

TypeScript

TypeScript client libraries for Seismic

Seismic provides two TypeScript packages:

Package

Purpose

Use when

Privy

Set up Privy with Seismic for email and social login

Privy provides email, social, and embedded wallet authentication. This guide shows how to integrate Privy with Seismic React for apps that need flexible onboarding beyond browser extension wallets.

Prerequisites

npm install @privy-io/react-auth @privy-io/wagmi wagmi viem @tanstack/react-query seismic-react seismic-viem

You need a Privy App ID from the Privy Dashboard.

Step 1: Configure Privy with Seismic Chain

Define the Seismic chain configuration for Privy:

Step 2: Set Up wagmi Config

Create a wagmi config using Privy's wagmi integration:

Step 3: Set Up Providers

Nest the providers in the correct order -- Privy wraps wagmi, and ShieldedWalletProvider goes inside:

Privy's embedded wallets work seamlessly with Seismic -- users don't need a browser extension. Privy creates a wallet automatically when users sign in with email or social accounts.

Use Privy's hooks to trigger the login modal:

Step 5: Use Shielded Hooks

Once authenticated, use seismic-react hooks as normal:

Complete Example

Seismic Testnet

Seismic public testnet chain configuration

The Seismic public testnet is the primary network for development and testing. seismicTestnet is a RainbowKit-compatible chain object that wraps the seismic-viem testnet definition with RainbowKit metadata.

Configuration

Property

Examples

Complete runnable examples for Seismic React

Complete working examples demonstrating common Seismic React patterns. Each example is self-contained and can be copied into a new project.

Available Examples

Example

Description

Clown Beatdown

Imagine a clown standing in front of you, taunting the crowd. Hidden in the clown's pockets are secrets — strings that only become visible once the clown is knocked out. There are primarily two actions you can take: hitting the clown or adding secrets to the clown's pockets. Hitting the clown reduces its stamina by one, bringing it closer to being knocked out. Adding a secret stores an encrypted string that no one can read until it's revealed. You can only rob the clown of a secret if you contributed to knocking it out, i.e., you hit the clown at least once in the current round. This collaborative challenge is the heart of the Clown Beatdown game, and it's all powered by the ClownBeatdown smart contract. Let's dive into the inner workings of the contract and uncover how each part fuels this game.

The contract can be found in the contracts/src/ClownBeatdown.sol file of the starter repo.

State variables

initialClownStamina and clownStamina

Think of stamina as the clown's durability. initialClownStamina is the clown's starting strength, and clownStamina tracks how much remains as players hit it.

secrets, secretsCount, and secretIndex

These are the hidden values at the heart of the game. secrets is a mapping of sbytes (shielded bytes) — encrypted strings stored on-chain that remain hidden until revealed. secretsCount tracks how many secrets have been added. secretIndex is a suint256 (shielded integer) that determines which secret will be revealed when the clown is robbed. Because secretIndex is shielded, no one can predict which secret will be returned.

round

A counter that increments with each new round/reset, ensuring every round has a fresh clown to beat down.

hitsPerRound

A mapping that records every player's contribution to the current round, ensuring only participants can rob the clown's secret.

Functions

addSecret (string _secret)

This function allows anyone to add a secret to the clown's pool. Since addSecret converts a plain string into sbytes (shielded bytes) and stores it in the secrets mapping, it performs a shielded write — the secret's contents are encrypted on-chain and invisible to observers.

What happens:

Converts the input string to sbytes and stores it in the secrets mapping
Increments secretsCount
Re-picks a random secretIndex

hit ( )

This function allows a player to hit the clown, reducing its stamina and bringing it one step closer to being knocked out:

What happens:

Checks if the clown is still standing (clownStamina > 0)
If it is, decrements clownStamina by 1
Increases the player who called hit()'s contribution in the current round (hitsPerRound[round][playerAddress]

rob ( )

This function allows contributors to the current round to steal a randomly selected secret from the clown. Since this is a view function that reveals an sbytes value, calling this function constitutes a signed read.

What happens:

Requires the clown to be knocked out (requireDown modifier)
Ensures the function caller contributed to knocking out the clown for this round (onlyContributor modifier)
Returns the secret at the shielded secretIndex position, decrypted from

reset ( )

This function resets the clown for a new round of gameplay:

What happens:

Requires the clown to be knocked out (requireDown modifier)
Restores clownStamina to initialClownStamina
Picks a new random secretIndex

Modifiers

Modifiers enforce the rules of the game:

requireDown

Ensures that rob() and reset() can only be called if the clown's stamina has reached zero.

requireStanding

Ensures that hit() can only be called while the clown still has stamina remaining.

onlyContributor

Restricts access to rob(), and hence the secret being revealed, only to players who contributed at least one hit in the current round.

Casting

Explicit Casting Only

Shielded types and their unshielded counterparts do not support implicit casting. You must always cast explicitly. This is a deliberate design decision -- every conversion between shielded and unshielded types is a potential information boundary, and the compiler requires you to be explicit about crossing it.

uint256 publicNumber = 100;

// Implicit casting -- will NOT compile
suint256 shielded = publicNumber; // Error

// Explicit casting -- correct
suint256 shielded = suint256(publicNumber); // OK

This applies to all shielded types: suint, sint, sbool, saddress, and sbytes.

For integer literals specifically, you can use the instead of an explicit cast: suint256 x = 42s; is equivalent to suint256 x = suint256(42);. The explicit cast is still required when converting from a variable.

Shielding Values (Unshielded to Shielded)

When you cast from an unshielded type to a shielded type, you are "shielding" the value -- moving it from the public domain into confidential storage/computation.

Privacy consideration: When going from unshielded to shielded, the original unshielded value is visible in the transaction trace at the point of casting. Observers can see what value was shielded. The value only becomes confidential after the cast, in subsequent operations.

If you need the value to be confidential from the start, it should arrive as encrypted calldata via a Seismic transaction (type 0x4A), not be cast from a public variable.

Unshielding Values (Shielded to Unshielded)

When you cast from a shielded type to an unshielded type, you are "unshielding" the value -- making it publicly visible.

Privacy consideration: When going from shielded to unshielded, the final unshielded value is visible in the transaction trace. Observers can see the result. This permanently exposes the value.

This is sometimes necessary (e.g., returning a value from a view function or interfacing with a non-shielded contract), but you should be deliberate about when and why you do it.

Casting `saddress` to Payable

saddress payable is a valid type, but it does not unlock any extra operations — .transfer(), .send(), and .balance are all blocked on shielded addresses regardless of payability. The payable marker exists for type-system consistency (e.g., contracts with receive() payable convert to saddress payable), not for sending ETH.

To actually send ETH to a shielded address, you must unshield it first:

Privacy consideration: Unshielding to address payable exposes the address in the transaction trace.

You can also convert in the other direction:

Size Casting Between Shielded Integers

You can cast between different sizes of shielded integers, just as you can with regular Solidity integers:

The same rules that apply to regular Solidity integer casting apply here:

Widening (smaller to larger): Always safe, the value is preserved.
Narrowing (larger to smaller): May truncate the value if it exceeds the target type's range.

You can also cast between signed and unsigned shielded integers:

Common Patterns

Returning values from view functions

Since shielded types cannot be returned from public or external functions, you must unshield them first:

Returning an unshielded value from a view function makes it visible to the caller. If the caller should only see their own data, use access control and to ensure only authorized users can query it.

Interfacing with non-shielded contracts

When calling a contract that expects unshielded types, cast at the call boundary:

Shielding input from encrypted calldata

The only way to introduce a value that is private from the start is through encrypted calldata, where the value is never visible in plaintext on-chain:

Security Implications

Every cast between shielded and unshielded types is a potential information leak point. Keep these principles in mind:

Unshielded-to-shielded casts expose the input value in the trace. If the value was meant to be secret from the start, use encrypted calldata instead.
Shielded-to-unshielded casts expose the output value in the trace. Only unshield when you intend the value to become public.
Minimize casts. The fewer times you cross the shielded/unshielded boundary, the smaller your attack surface.

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

The Seismic Solidity compiler

The Seismic compiler (ssolc) is a fork of solc that understands shielded types. When you write:

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

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

The client calls seismic_getTeePublicKey on the RPC to fetch the network's TEE public key.
The client performs ECDH key agreement between the user's private key and the TEE public key to derive a shared secret.
The calldata is encrypted using AEAD (authenticated encryption with associated data).

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 .

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:

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 .

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:

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

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

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 (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 . This is built on a forked version of revm.

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:

(fork of alloy-core): Shielded types and FlaggedStorage primitives.
(fork of alloy-trie): Merkle trie encoding for FlaggedStorage values.
(fork of revm): CLOAD/CSTORE opcodes, Seismic precompiles, and FlaggedStorage access rules.

Plus two original repos:

: Consensus client.
: ECDH + AES-GCM crypto for transaction encryption/decryption.
: Rust SDK with TxSeismic type and encryption-aware providers.

For the full list and dependency flow, see .

Summit (consensus)

Summit is Seismic's consensus layer, built on 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:

A new node generates an attestation report inside its TEE.
The report is sent to existing nodes for verification.
Existing nodes check that the report was generated by genuine Intel TDX hardware and that the code measurement matches the approved build.

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.

ShieldedContract

Sync contract wrapper with shielded and transparent namespaces

Synchronous contract wrapper providing encrypted and transparent interaction with Seismic contracts.

Overview

ShieldedContract is the primary sync interface for interacting with Seismic smart contracts. It provides five namespaces for different interaction modes: encrypted writes (.write), encrypted reads (.read), transparent writes (.twrite), transparent reads (.tread), and debug writes (.dwrite). Each namespace dynamically exposes contract methods based on the provided ABI.

Definition

Constructor Parameters

Parameter

Type

Required

Description

Namespaces

`.write` - Encrypted Write

Sends encrypted transactions using TxSeismic (type 0x4a). Calldata is encrypted before broadcast.

Returns: HexBytes (transaction hash)

Positional Arguments: *args - ABI function arguments (e.g. contract.write.transfer(to, amount))

Optional Parameters:

value: int - Wei to send (default: 0)
gas: int | None - Gas limit (default: 30_000_000 when omitted)

`.read` - Encrypted Read

Executes encrypted signed eth_call with encrypted calldata. Result is decrypted and ABI-decoded by the SDK. Single-output functions return the value directly (e.g. int, bool); multi-output functions return a tuple.

Returns: Any (ABI-decoded Python value)

Positional Arguments: *args - ABI function arguments (e.g. contract.read.balanceOf(owner))

Optional Parameters:

value: int - Wei for call context (default: 0)
gas: int - Gas limit (default: 30_000_000)

`.twrite` - Transparent Write

Sends standard eth_sendTransaction with unencrypted calldata.

Returns: HexBytes (transaction hash)

Positional Arguments: *args - ABI function arguments

Optional Parameters:

value: int - Wei to send (default: 0)
**tx_params: Any - Additional transaction parameters (gas, gasPrice, etc.)

`.tread` - Transparent Read

Executes standard eth_call with unencrypted calldata. Result is ABI-decoded by the SDK. Single-output functions return the value directly; multi-output functions return a tuple.

Returns: Any (ABI-decoded Python value)

Positional Arguments: *args - ABI function arguments

`.dwrite` - Debug Write

Like .write but returns debug information including plaintext and encrypted views. Transaction is actually broadcast.

Returns:

Positional Arguments: *args - ABI function arguments

Optional Parameters: Same as .write

Examples

Basic Encrypted Write

Encrypted Read

Transparent Operations

Debug Write

With Transaction Parameters

Using EIP-712 Signing

Instantiation via Client

Notes

Dynamic method access: Contract methods are accessed via __getattr__, so contract.write.setNumber() dynamically resolves to the ABI function
ABI remapping: Shielded types (suint256, sbool, saddress) are remapped to standard types for encoding while preserving original names for selector computation

Signed Reads

Let users check their own balance without exposing it to others

The SRC20 contract stores balances as suint256, which means there is no public getter. This chapter shows how to let users query their own balance securely using signed reads. Estimated time: ~15 minutes.

The problem

In a standard ERC20, balanceOf is a public mapping. Anyone can call balanceOf(address) and see any account's balance. In the SRC20, two things prevent this:

Shielded types cannot be public. The suint256 value type means the automatic getter would try to return a shielded type from an external function, which the compiler rejects.
Vanilla eth_call has no sender identity. On Seismic, the from field is zeroed out for unsigned eth_call

So you need two things: a way for the contract to verify who is asking, and a way to return the value only to that person.

Signed reads

A signed read solves both problems. It is a Seismic transaction (type 0x4A) sent to the eth_call RPC endpoint instead of eth_sendRawTransaction. Because it is a valid signed transaction:

The from field is cryptographically verified, so the contract can trust msg.sender.
The response is encrypted to the sender's encryption public key (included in the Seismic transaction's elements). Even if someone intercepts the response, they cannot decrypt it.
The signed_read

From the contract's perspective, a signed read looks like a normal view function call. The difference is entirely at the transport layer.

Contract implementation

Add a balanceOf function that requires the caller to be the account owner:

Note the naming here. The mapping balanceOf is internal (no public modifier), so there is no collision with the function name. The function acts as the explicit getter that replaces the auto-generated one.

This function does three things:

Checks msg.sender -- Only the account owner can query their own balance. With a vanilla eth_call, msg.sender would be address(0) and this check would always fail. With a signed read, msg.sender is the actual caller.
Casts to

Allowance checking

The same pattern applies to allowances:

Here, either the owner or the spender can check the allowance. Both parties have a legitimate reason to know the value.

Client-side code

On the client side, seismic-viem handles signed reads automatically under the hood. When you use a ShieldedWalletClient or a ShieldedContract, read calls are sent as signed reads. If you need an unsigned read (a vanilla eth_call), use contract.tread instead.

Using a shielded contract instance

The token.read.balanceOf() call is sent as a signed read under the hood. The wallet client signs the request, the node verifies the signature, executes the view function with the correct msg.sender, and encrypts the response to the caller's key.

Using the wallet client directly

You can also call readContract on the wallet client:

Both approaches produce the same signed read.

Security model

The signed read has several layers of protection:

Property

How it works

The result is that only the account owner can view their balance, and the balance is never exposed in plaintext outside the TEE.

A note on privacy tradeoffs

With this implementation, each user can only see their own balance. They cannot see anyone else's balance. This is the strictest privacy model. In the next chapter, , we will add authorized roles (such as compliance officers) who can view specific balances when required -- without compromising privacy for everyone else.

Shielded Writes

Send encrypted write transactions with shieldedWriteContract

Shielded writes encrypt transaction calldata before submission. This prevents calldata from being visible on-chain -- an observer can see that a transaction was sent to a particular contract address, but not what function was called or what arguments were passed.

seismic-viem provides several approaches:

contract.write.functionName() -- smart routing via getShieldedContract. Auto-detects shielded parameters and encrypts only when needed.
contract.swrite.functionName() -- force shielded via . Always encrypts, regardless of parameter types.
shieldedWriteContract() -- standalone function, same API shape as viem's writeContract. Always encrypts.
walletClient.writeContract() -- smart routing via the wallet client. Same auto-detection as contract.write.
walletClient.swriteContract() -- force shielded via the wallet client. Always encrypts.

The shielded paths all produce the same on-chain result: an encrypted type 0x4A Seismic transaction.

Standalone: `shieldedWriteContract`

Parameters

Parameter

Type

Required

Description

Returns

Promise<Hash> -- the transaction hash.

Example

Send + Inspect: `shieldedWriteContractDebug`

Broadcasts a shielded transaction (like shieldedWriteContract) and additionally returns the plaintext transaction view and the shielded (encrypted) transaction view alongside the resulting transaction hash. Useful for inspecting exactly what the SDK encrypted and submitted.

Despite the "debug" flavor of the name, shieldedWriteContractDebug does send the transaction -- the returned txHash is a real on-chain hash, not a dry run.

Low-level: `sendShieldedTransaction`

For cases where you have raw transaction data instead of ABI-encoded calls -- for example, contract deployments, pre-encoded calldata, or bypassing the contract abstraction entirely:

How It Works

When you call shieldedWriteContract (or contract.swrite.functionName), the SDK performs the following steps:

ABI-encode the function call into plaintext calldata
Build Seismic metadata -- encryption nonce, recent block hash, expiry block
Encrypt calldata with AES-GCM using a shared key derived via ECDH between your ephemeral keypair and the node's TEE public key

The encrypted calldata is bound to the transaction context (chain ID, nonce, block hash, expiry) via AES-GCM additional authenticated data, so it cannot be replayed or tampered with.

Security Parameters

Every shielded transaction includes a block-hash freshness check and an expiry window. The defaults are sensible for most cases, but you can override them per-call via SeismicSecurityParams, passed as the optional third argument to shieldedWriteContract, shieldedWriteContractDebug, sendShieldedTransaction, signedReadContract, and signedCall:

Parameter

Type

Default

Description

securityParams only applies to the low-level shielded paths (shieldedWriteContract, shieldedWriteContractDebug, sendShieldedTransaction, signedReadContract, signedCall, and the .swrite/.sread/.dwrite

The default 100-block window, random nonce, and latest block hash are appropriate for nearly all use cases. Override these only if you have a specific reason -- for example, reducing the window for time-sensitive operations or pinning the block hash in tests.

Encrypted Events

Emit transfer events with encrypted amounts using AES precompiles

In the previous chapter, we cast suint256 amounts to uint256 before emitting events. This works, but it reveals the amount in the public event log. This chapter shows how to encrypt event data so that only the intended recipients can read it. Estimated time: ~20 minutes.

The problem

Events in Ethereum (and Seismic) are stored in transaction logs, which are public. You cannot use shielded types directly in event parameters:

// This will NOT compile
event Transfer(address indexed from, address indexed to, suint256 amount);

The compiler rejects this because event data is written to public logs, and shielded types are only meaningful in contract storage. If you cast to uint256 and emit, the amount appears in plaintext in the log -- defeating the purpose of shielding it in the first place.

The solution

Use Seismic's AES-GCM precompiles to encrypt the sensitive data before emitting it. The event carries opaque bytes that only the intended recipient can decrypt.

The modified event signature uses bytes instead of uint256 for the amount:

The from and to addresses remain as indexed parameters. These are public -- observers can see who is transacting with whom. Only the amount is encrypted. If you need to hide the participants as well, you can encrypt those too, but that is less common for a token.

Step by step

The encryption flow uses three of Seismic's precompiles:

Step 1: Derive a shared secret with ECDH

The ECDH precompile at address 0x65 performs Elliptic Curve Diffie-Hellman key agreement. Given a private key and a public key, it produces a shared secret that both parties can independently derive.

For event encryption, the contract needs a keypair. The private key must not be passed as a constructor argument -- constructor calldata is not encrypted (CREATE/CREATE2 transactions are standard Ethereum transaction types), so the key would leak in the deployment data.

Instead, set the key after deployment via a Seismic transaction (type 0x4A), which encrypts calldata:

Because setContractKey is called via a Seismic transaction, the private key is encrypted in the calldata before it leaves the caller's machine. The key is stored as sbytes32, so the compiler routes it through shielded storage — observers see 0x00...0 instead of the actual key.

To derive a shared secret with a specific recipient, the contract calls the ECDH precompile with its own private key and the recipient's public key:

Step 2: Derive an encryption key with HKDF

The raw ECDH shared secret should not be used directly as an encryption key. The HKDF precompile at address 0x68 derives a proper cryptographic key from the shared secret:

The second argument is a context string (sometimes called "info" in HKDF terminology). Using a unique context string for each purpose ensures that the same shared secret produces different keys for different uses.

Step 3: Encrypt with AES-GCM

The AES-GCM Encrypt precompile at address 0x66 encrypts the data:

Step 4: Emit the encrypted event

Putting it all together in an internal helper:

Full implementation

Here is the updated transfer function using encrypted events:

Users register their public key by calling registerPublicKey once. After that, any transfer they receive will emit an event encrypted to their key.

Decrypting off-chain

The recipient can decrypt the event data by performing the reverse of the encryption flow:

Take the contract's public key (stored on-chain and readable by anyone).
Combine it with their own private key using ECDH to derive the same shared secret.
Run HKDF with the same context string ("src20-transfer-event") to derive the same encryption key.

Decrypt events client-side using the ECDH shared secret and AES-GCM decryption. See the for the cryptographic primitives.

Who can read what

Here is the visibility breakdown for each piece of data in a Transfer event:

Data

Who can see it

Why

The sender can also decrypt the amount because they know the plaintext -- they created the transaction. If you need the sender to be able to decrypt from the event log as well (for example, for transaction history), you can emit a second event encrypted to the sender's key, or encrypt to both keys and include both ciphertexts.

Encrypted events add gas cost for the precompile calls. For applications where the event amount being public is acceptable, the simpler uint256(amount) cast from the previous chapter is more gas-efficient. Choose the approach that matches your privacy requirements.

Signed Reads

Authenticated read calls that prove caller identity

On standard Ethereum, eth_call can spoof any from address -- there is no signature check. Seismic prevents this: all unsigned eth_call requests have msg.sender set to the zero address. To read shielded data that depends on msg.sender, you need a signed read: a signed transaction submitted to eth_call that proves the caller's identity.

Why Signed Reads Matter

Contracts can use msg.sender in view functions to gate access to shielded data. A common example: a token contract with a balanceOf() that takes no arguments and uses msg.sender internally to look up the caller's balance. Without a signed read, the contract sees the zero address and returns that address's balance -- which is almost certainly zero.

seismic-viem provides several approaches:

contract.read.functionName() -- smart routing via . Auto-detects shielded parameters and uses signed read only when needed.
contract.sread.functionName() -- force signed read via . Always uses signed read regardless of parameter types.

The signed read paths all encrypt the calldata, sign it, and decrypt the response automatically.

Standalone: `signedReadContract`

Parameters

signedReadContract(client, parameters, securityParams?)

Parameter

Type

Required

Description

The optional third argument securityParams: SeismicSecurityParams accepts advanced Seismic metadata overrides (see ). Most callers should omit these; they are mainly useful for deterministic tests/debugging, explicit expiry control, and low-level interop.

Returns

Promise<ReadContractReturnType> -- the decoded return value, typed according to the ABI.

If the client has no account configured, signedReadContract falls back to a standard readContract (transparent eth_call). Pass an account-bearing ShieldedWalletClient to get the signed read behavior.

Example

Low-level: `signedCall`

For cases where you have raw calldata instead of ABI-encoded parameters -- for example, pre-encoded data or non-ABI interactions:

signedCall also accepts SeismicSecurityParams as a third argument for overriding the encryption nonce, block hash, or expiry window. See for the full parameter table.

How It Works

When you call signedReadContract (or contract.sread.functionName), the SDK performs the following steps:

ABI-encode the function call into plaintext calldata
Build Seismic metadata with signedRead: true
Encrypt calldata with AES-GCM using the shared key derived via ECDH

Both the calldata you send and the result you receive are encrypted. An observer watching the network can see that a call was made to a particular contract address, but not what function was called or what was returned.

Signed Read vs Transparent Read

The smart .read namespace handles most cases correctly by inspecting the ABI. Use .sread when you need the response encrypted even though the function has no shielded input parameters. Use .tread only for public data where you don't need authentication.

.tread and walletClient.treadContract reject the account option and will throw. On Seismic, transparent eth_call zeroes out from on the node, so any account you pass would silently be ignored. For any sender-aware read, use .sread / sreadContract.

General

Overview

Welcome

hashtagOne letter changes everything

Why Seismic

hashtagThe transparency problem

hashtagWhy existing privacy solutions fall short

hashtagThe Seismic approach

hashtagShielded types in the compiler

hashtagTEE-based execution

hashtagWhat does not change

Getting Started

Installation

hashtagSystem requirements

Quickstart

Web Interface

hashtagRunning the web app

REST API

hashtagRunning the server

hashtagGET /api/tokens

hashtagRequest

hashtagResponse

hashtagGET /api/token/{address}

hashtagRequest

hashtagResponse

hashtagError response

hashtagWhat the API can and cannot read

Tutorials

SRC20: Private Token

hashtagWhat you'll build

hashtagWhat makes this special

hashtagPrerequisites

hashtagWhat you'll learn

hashtagTutorial structure

Verify devtool installation

Create project structure

Initialize contracts

Initialize the CLI

Writing the Contract

hashtagWhat You'll Learn

Ch 1: The Secrets Pool

hashtagDefining the secrets pool

Seismic-viem Primer

hashtagShielded wallet client

hashtagShielded contract

Building the Frontend

hashtagWhat You'll Learn

hashtagOverview of Chapters

Seismic Solidity

Collections

hashtagShielded Arrays

hashtagShielded Mappings

Best Practices

hashtagAlways Use Seismic Transactions for Shielded Parameters

Clients

Overview

hashtagTypeScript

hashtagseismic-viem

hashtagseismic-react

hashtagPython — seismic-web3

hashtagRust — seismic-alloy

TypeScript

Privy

hashtagPrerequisites

hashtagStep 1: Configure Privy with Seismic Chain

hashtagStep 2: Set Up wagmi Config

hashtagStep 3: Set Up Providers

hashtagStep 4: Add Login Button

hashtagStep 5: Use Shielded Hooks

hashtagComplete Example

hashtagSee Also

Seismic Testnet

hashtagConfiguration

Examples

hashtagAvailable Examples

SRC20: Private Token

hashtagWhat you'll build

hashtagWhat makes this special

hashtagPrerequisites

hashtagWhat you'll learn

One letter changes everything

The transparency problem

Why existing privacy solutions fall short

The Seismic approach

Shielded types in the compiler

TEE-based execution

What does not change

System requirements

Running the web app

Running the server

GET /api/tokens

Request

Response

GET /api/token/{address}

Request

Response

Error response

What the API can and cannot read

What you'll build

What makes this special

Prerequisites

What you'll learn

Tutorial structure

What You'll Learn

Defining the secrets pool

Shielded wallet client

Shielded contract

What You'll Learn

Overview of Chapters

Shielded Arrays

Shielded Mappings

Always Use Seismic Transactions for Shielded Parameters

TypeScript

seismic-viem

seismic-react

Python — seismic-web3

Rust — seismic-alloy

Prerequisites

Step 1: Configure Privy with Seismic Chain

Step 2: Set Up wagmi Config

Step 3: Set Up Providers

Step 4: Add Login Button

Step 5: Use Shielded Hooks

Complete Example

See Also

Configuration

Available Examples

What you'll build

What makes this special

Prerequisites

What you'll learn

Tutorial structure

Prerequisites

Step 1: Configure Privy with Seismic Chain

Step 2: Set Up wagmi Config

Step 3: Set Up Providers

Step 4: Add Login Button

Step 5: Use Shielded Hooks

Complete Example

See Also

The transparency problem

Why existing privacy solutions fall short

The Seismic approach

Shielded types in the compiler

TEE-based execution

What does not change

One letter changes everything

What you can build

3-minute quickstart

Find what you need

Pre-requisite knowledge

Work with us

System requirements

Running the web app

What You'll Learn

Defining the secrets pool

Overview of Chapters

Install the local development suite

Set up the VSCode extension

Wagmi configuration