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 0x00...0 instead of actual balances and amounts. Everything else — the Solidity syntax, the EVM execution model, the deployment flow — stays exactly the same.

What you can build

Shielded tokens — ERC20s where balances and transfer amounts are hidden from observers
Confidential DeFi — AMMs and lending protocols where positions, prices, and liquidation thresholds are shielded
Compliant finance — Privacy with built-in access control so regulators can verify without exposing user data
Private voting — On-chain governance where votes are secret until tallied

3-minute quickstart

Already have Rust and the Seismic tools installed?

You just ran shielded contract tests locally. See the full quickstart for next steps.

Find what you need

I want to...

Go to

Understand why Seismic exists

Why Seismic

See how it works under the hood

How Seismic Works

Set up my dev environment

Installation

Run my first shielded contract

Quickstart

Build a complete app step by step

Clown Beatdown Tutorial

Build a shielded ERC20 token

SRC20 Tutorial

Learn about shielded types

Shielded Types

Integrate a frontend

Client Libraries

Deploy to testnet

Migrating from Ethereum

Understand the transaction lifecycle

Seismic Transaction

Run a node

Node Operator FAQ

Pre-requisite knowledge

Our documentation assumes some familiarity with blockchain app development. Before getting started, it'll help if you're comfortable with:

If you're new to blockchain app development or need a refresher, we recommend starting out with the CryptoZombies tutorial.

Work with us

If you might benefit from direct support from the team, please don't hesitate to reach out to dev@seismic.systems. We pride ourselves in fast response time.

You can also check out our X account for the latest updates, or join our Discord community.

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

ZK chains (Aztec, Aleo, Mina)

Require new languages (Noir, Leo, o1js). You leave Solidity, Foundry, and the entire EVM ecosystem behind.

Mixers (Tornado Cash)

Only work for transfers. You can obscure the sender, but contract state is still public. No programmable privacy.

L2 privacy layers

Sacrifice composability. Contracts on the privacy layer cannot natively interact with contracts on the base chain.

Homomorphic encryption (fhEVM)

Computationally expensive. Operations on encrypted data are orders of magnitude slower, limiting what you can practically build.

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, and solc. Your workflow does not change.
Same client libraries. seismic-viem extends Viem. seismic-react extends Wagmi. seismic-alloy extends Alloy for Rust. seismic_web3 extends web3.py for Python.
Same standards. ERC20 becomes SRC20. The interface is the same. The deployment flow is the same. The difference is that balances are private.
Same deployment flow. Write, test, deploy. The commands are sforge build, sforge test, sforge create. If you have deployed to Ethereum, you can deploy to Seismic.

Differences from Ethereum

Overview

The Seismic EVM is approximately a superset of the EVM

What's the same

Transaction construction and serialization identical to Ethereum (with one new transaction type)
Address generation, gas estimation, and signing work the same as Ethereum
Almost all RPC methods are identical to reth
Standard Solidity bytecode will behave identically on Seismic, with (e.g., SSTORE reverts on shielded slots)
Seismic supports all of Ethereum's opcodes & precompiles
EIP-1559 transactions follow standard EIP-1559 fee rules. Seismic transactions (type 0x4A) use legacy fee pricing
Seismic will produce empty blocks when there are no pending transactions

Shielded storage: Solidity contracts can store private data on-chain
Runs in a TEE: Seismic nodes must run in Trusted Execution Environments
Seismic transaction: We added a new transaction type that allows you to encrypt your calldata

– load shielded data from storage
– write shielded data to storage
– get the block timestamp in milliseconds. Note that block.timestamp still returns seconds, matching standard Solidity. Use block.timestamp_ms for millisecond precision

The transaction with type 0x4a allows users to encrypt their calldata. These otherwise work just like legacy transactions. We also support the other standard Ethereum transaction types (Legacy, EIP-1559, EIP-2930, EIP-4844, EIP-7702)

All standard Ethereum precompiles are still available. Seismic added 6 new to our EVM:

— securely generate a random number
— Elliptic Curve Diffie-Hellman, for generating a shared secret given a public key and secret key
— encrypt data with AES-GCM

Seismic uses the same staking contract as Ethereum, which is hardcoded into our Genesis block at address 0x00000000219ab540356cbb839cbe05303d7705fa

We will often produce multiple blocks in the same second, yet Ethereum's block timestamps are expressed in terms of unix seconds. Our solution to this:

Block headers and the EVM use timestamps in milliseconds internally
In Seismic Solidity, block.timestamp returns unix seconds, just like in standard Solidity. We added block.timestamp_ms which returns unix milliseconds. block.timestamp_seconds is an alias for block.timestamp

We support almost every RPC endpoint in Reth, and have added a few more of our own. See the full reference for details.

Seismic-specific methods:

— returns the TEE's encryption public key for ECDH key exchange

Modified Ethereum methods:

— zeroes the from field on unsigned calls; supports via type 0x4A
— accepts Seismic transaction type 0x4A with encrypted calldata

Use Cases

Seismic's shielded types let you add privacy to any smart contract pattern. Below are five categories with code snippets showing how each looks in Seismic Solidity.

Private tokens (SRC20)

An ERC20 with shielded balances and transfer amounts. Users can check their own balance through signed reads, but no one else can see it.

mapping(address => suint256) balanceOf;
mapping(address => mapping(address => suint256)) allowance;
suint256 totalSupply;

function transfer(address to, suint256 amount) public {
    balanceOf[msg.sender] -= amount;
    balanceOf[to] += amount;
}

The only difference from a standard ERC20: uint256 becomes suint256. The compiler routes all balance reads and writes through shielded storage automatically. Observers see 0x00...0 for all balances and amounts.

For a full walkthrough, see the SRC20 tutorial.

Confidential DeFi

An AMM where liquidity positions, reserves, and swap amounts are hidden from observers. This prevents front-running and MEV extraction because bots cannot see the pool state or pending swaps.

The constant-product formula is standard AMM logic. Shielding the reserves and amounts means no one can compute the price impact of a pending swap or sandwich a user's trade.

Contracts can optionally implement access control over shielded data — for example, exposing a view function that only authorized addresses can call. This pattern is sometimes called an "Intelligence Contract": a shielded contract that selectively reveals information to specific parties.

In this example, balances are stored as suint256 so they are shielded by default. The getBalance function casts the shielded value to a regular uint256 for return, but only if the caller is the account owner or holds the COMPLIANCE_ROLE. Everyone else is rejected.

Secret ballot governance on-chain. Votes are hidden during the voting period. The tally can be revealed when voting ends, but individual votes remain private.

During voting, both the individual votes (hasVoted) and the running tallies (yesVotes, noVotes) are shielded. No one can see which way the vote is trending. After the deadline, getResults() casts the shielded tallies to public uint256 values so the outcome can be read.

Bids are hidden until the auction closes. No bidder can see what others have bid, eliminating bid sniping and strategic underbidding.

Each bid is stored as a suint256, and the highest bidder's address is stored as an saddress. During the auction, the contract tracks the leading bid internally, but no one outside the TEE can see any bid amounts or the current leader. After the auction ends, getWinner() reveals the result by casting shielded values to their public counterparts.

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
MacOS, Ubuntu, or Windows (other Linux distros may work but are not officially tested)

Install the local development suite

The local development suite uses sforge as the testing framework, sanvil as the local node, and ssolc as the compiler.

Install rust and cargo on your machine if you don't already have them. Default installation works well.

Download and execute the sfoundryup installation script.

Install sforge, sanvil, ssolc. Expect this to take between 5-20 minutes depending on your machine.

(Optional) Remove old build artifacts in existing projects. You can ignore this step if you aren't working with existing foundry projects.

Set up the VSCode extension

We recommend adding syntax highlighting via the seismic (or seismic for Open VSX) extension from the VSCode marketplace. If you already have the solidity extension, you'll have to disable it while writing Seismic code.

Development Toolkit

Use sfoundry to write and test smart contract code locally before deployment

Mappings to foundry

Seismic's development toolkit closely mirrors Foundry (it's a fork!). The mapping is as follows:

You should use the righthand version of all tools when developing for Seismic to get expected behavior. Our documentation assumes familiarity with foundry.

Quick actions

Substitute sforge for forge to execute against Seismic's superset of the EVM. More on this in the next section.

# Initializes a project called `Counter`
sforge init Counter

# Run tests for the Counter contract
sforge test

# Use sforge scripts to deploy the Counter contract
# Running `sanvil` @ http://localhost:8545
# Set the private key in the env
export PRIVATE_KEY="0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80" # Address - 0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266
# Run the script and broadcast the deploy transaction
sforge script script/Counter.s.sol --rpc-url http://127.0.0.1:8545 --broadcast --private-key $PRIVATE_KEY

Local node

Use sanvil to run a local Seismic node for development and testing:

This starts a local node at http://localhost:8545 with pre-funded accounts, similar to Foundry's anvil.

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.

Deploy an SRC20 in 60 Seconds

Deploy a private SRC20 token on Seismic testnet with a single command — no compiler required

The SRC20 Factory is a pre-deployed contract on Seismic testnet that lets anyone create a private token without installing sforge or writing a single line of Solidity. You give it a name, symbol, and supply; it hands back a deployed token address.

Quickstart

bunx create-src20

That's it. The CLI walks you through the rest interactively, or you can pass everything up front:

bunx create-src20 \
  --name "My Private Token" \
  --symbol "MPT" \
  --supply 1000000 \
  --key 0xYourPrivateKey

Example output:

  Create SRC20 Token on Seismic

  Deploying to Seismic testnet...

  Token deployed!

  Address:  0xabc...
  Name:     My Private Token
  Symbol:   MPT
  Supply:   1,000,000
  Owner:    0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266
  Tx:       0xdef...
  Explorer: https://seismic-testnet.socialscan.io/address/0xabc...

CLI flags

Flag

Description

Default

Every deployed token is a full SRC20Token contract — Seismic's private variant of ERC20. Balances, transfer amounts, and allowances are encrypted on-chain using suint256 shielded types. Outside observers see only encrypted ciphertext. The token deployer becomes the owner and has exclusive mint and burn rights.

The factory exposes four interfaces depending on how you want to integrate:

Interface

When to use

Chain ID: 5124 (Seismic testnet)
Factory address: 0x87F850cbC2cFfac086F20d0d7307E12d06fA2127
Explorer:

TypeScript SDK

API reference for the @seismic/src20-sdk package used internally by the CLI and web app

@seismic/src20-sdk is the TypeScript library that powers the CLI and web interface in this repo. It wraps the SRC20 Factory contract and exposes three functions and the contract ABIs.

@seismic/src20-sdk is an internal workspace package — it is not published to npm. It is used by the packages/cli and packages/web packages within this monorepo. This page documents its API surface as a reference.

createToken

Deploys a new SRC20 token through the factory and returns the deployed address.

Signature

async function createToken(
  client: ShieldedWalletClient,
  params: CreateTokenParams,
): Promise<CreateTokenResult>;

Parameters

Parameter

Type

Required

Description

Reads public metadata from a deployed SRC20 token using a standard public client.

Resolves the factory contract address for a given chain ID. Throws if the chain is not supported.

The raw mapping of chain IDs to factory addresses:

The package exports the full contract ABIs:

SRC20FactoryAbi — createToken, getTokenCount, tokens(uint256), TokenCreated event
SRC20TokenAbi — name

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:

Deploying a token

Open the web app and connect MetaMask
Switch to the Seismic testnet (chain ID 5124)
Fill in the token name, symbol, and initial supply
Click Deploy and confirm the transaction in your wallet
The deployed token address and transaction hash appear on success

Supply is entered in whole tokens. Entering 1000000 mints 1,000,000 × 10¹⁸ base units.

Wagmi configuration

The web app connects MetaMask to Seismic testnet via wagmi:

Other wallet connectors (WalletConnect, Coinbase, etc.) are not configured by default but can be added following the wallet guides.

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

GET http://localhost:3001/api/tokens

Response

{
  "count": 2,
  "tokens": [
    {
      "address": "0xabc123...",
      "name": "My Private Token",
      "symbol": "MPT",
      "decimals": 18,
      "owner": "0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266",
      "total_supply": "1000000000000000000000000"
    },
    {
      "address": "0xdef456...",
      "name": "Another Token",
      "symbol": "AT",
      "decimals": 6,
      "owner": "0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266",
      "total_supply": "500000000000"
    }
  ]
}

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.

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

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

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.

Think of stamina as the clown's durability. initialClownStamina is the clown's starting strength, and clownStamina

Setting Up Your Project

In this chapter, you'll set up the foundation for the Clown Beatdown game using a clean and modular monorepo-style workspace. This structure separates concerns into distinct areas, making your project easier to navigate and maintain. You'll create a contracts directory to house your Seismic smart contracts and tests, and a cli directory to serve as the command-line interface for interacting with those contracts. By the end of this chapter, you'll have a fully initialized project, complete with dependencies, formatting tools, and a seamless environment for both contract development and interaction.

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 bun installed on your machine. If you do not have bun installed, follow the instructions here 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:

cd packages/contracts

Initialize a project with sforge:

This command will:

Create the contract project structure (e.g., src/, test/, foundry.toml).
Automatically install the Forge standard library (forge-std) as a submodule.
Remove the .github workflow folder (not required)

Edit the .gitignore file to be the following:

Delete the default contract, test and script files (Counter.sol and Counter.t.sol and Counter.s.sol) and replace them with their ClownBeatdown counterparts (ClownBeatdown.sol, ClownBeatdown.t.sol and ClownBeatdown.s.sol):

These files are empty for now, but we will add to them as we go along.

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:

# Assuming you are currently in the contracts directory
cd ../cli

Initialize a new bun project

bun init -y

Now, create an src/ folder and move index.ts there.

Now, edit package.json to be the following:

Edit .gitignore to be:

Your environment is now set!

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:

Define a pool of shielded secrets using sbytes and a shielded index using suint256.
Build the stamina bar, the protective layer that guards the secrets, and implement a hit() function to reduce it.
Add a rob() function to reveal a randomly selected secret to authorized contributors.
Implement a reset mechanism to restart the game for multiple rounds.
Track player contributions in each round, ensuring that only contributors can rob the clown.

Overview of Chapters

Chapter 1: The Secrets Pool

You'll define the secrets pool using shielded storage (sbytes) and a shielded index (suint256), and implement an addSecret() function to populate it. This chapter introduces shielded writes.

Chapter 2: The Stamina Bar and Robbing Secrets

Learn how to build the stamina system, which protects the secrets from being accessed prematurely. You'll implement the hit() function to reduce stamina and the rob() function to reveal a secret once conditions are met.

Chapter 3: Reset Mechanism, Rounds, and Contributor Access

This chapter introduces a reset mechanism to enable multiple rounds of gameplay. You'll track contributions per round and ensure that only players who helped knock out the clown in a specific round can rob it. This chapter introduces signed reads.

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 packages/contracts/src/ClownBeatdown.sol and define the state variables:

We accept _clownStamina in the constructor but won't use it until Chapter 2, when we add the stamina system.

Add the addSecret function

Next, let's implement a function to add secrets to the pool. The addSecret function takes a plain string and converts it to sbytes for shielded storage:

Add the random index helper

The _randomIndex function generates a pseudo-random index into the secrets array using on-chain randomness sources:

What's happening here?

The addSecret function converts a plain string into sbytes (shielded bytes) and stores it in the secrets mapping. Because sbytes is a shielded type, the secret's contents are encrypted on-chain and invisible to observers.

The function also updates shielded state (secretIndex is a suint256), which makes a call to this function a shielded write.

Note that we're using two different shielded types here:

sbytes — for storing encrypted strings (the secrets themselves)
suint256 — for storing an encrypted integer (the index that determines which secret gets revealed)

Deploying

In this chapter, you'll deploy your ClownBeatdown contract to a local Seismic node for testing. By the end of this guide, you'll have a fully deployed contract that you can interact with using your CLI or scripts. Estimated Time: ~15 minutes.

Writing the deploy script

Navigate to the script folder in your project and open the ClownBeatdown.s.sol file located at:

packages/contracts/script

and add the following to it:

// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.13;

import {Script, console} from "forge-std/Script.sol";
import {ClownBeatdown} from "../src/ClownBeatdown.sol";

contract ClownBeatdownScript is Script {
    ClownBeatdown public clownBeatdown;

    function run() public {
        uint256 deployerPrivateKey = vm.envUint("PRIVKEY");

        vm.startBroadcast(deployerPrivateKey);
        clownBeatdown = new ClownBeatdown(3);
        vm.stopBroadcast();

        console.log("Deployed at:", address(clownBeatdown));
    }
}

This script will deploy a new instance of the ClownBeatdown contract with an initial stamina of 3. We'll add secrets separately in the next step, since addSecret performs shielded writes that need to be sent as on-chain transactions.

Deploying the contract

In a separate terminal window, run

in order to spin up a local Seismic node.

In packages/contracts, create a .env file and add the following to it:

The RPC_URL denotes the port on which sanvil is running and the PRIVKEY is one of the standard sanvil testing private keys.

Now, from packages/contracts, deploy the contract:

The output will show the deployed contract address (e.g. 0x5FbDB2315678afecb367f032d93F642f64180aa3).

Add secrets to the deployed contract using scast send. Replace <CONTRACT_ADDRESS> with the address from the previous step:

Your contract should be up and deployed to your local Seismic node with 5 secrets!

Building the CLI

In this section, you will write a CLI to interact with the deployed ClownBeatdown smart contract from scratch, simulating a multiplayer, multi-round game consisting of two players, Alice and Bob. At the end of this section, you will be able to see a full game play out on your local Seismic node! Estimated time: ~30 minutes

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:

const walletClient = await createShieldedWalletClient({
  chain: seismicChain,
  transport: httpTransport,
  privateKey: "0xabcdef...",
});

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.

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.

Ch 1: Constants and Utilities

In this chapter, you will learn about defining constants and utility functions which we will frequently use throughout the project. Estimated time: ~10 minutes

First, navigate to the root of the directory/monorepo and run bun install to install all the dependencies.

Now, navigate to make a lib folder inside packages/cli with the files constants.ts and utils.ts and navigate to it:

constants.ts

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

Ch 1: Project Setup and Providers

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

Ch 2: Contract Hooks

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

Ch 3: Game UI Components

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.

Shielded Literals

The s suffix lets you write shielded integer constants directly, without explicit casting. The compiler infers the concrete shielded type (suint8, suint256, sint128, etc.) from context.

This is equivalent to:

Both forms are valid. The s suffix is syntactic sugar — it produces the same bytecode.

Supported formats

The s suffix works with all numeric literal forms:

Type inference

The shielded type is inferred from the assignment target or surrounding expression:

Rules

No mixed arithmetic. You cannot mix shielded and non-shielded literals in the same expression:

No implicit conversion to non-shielded types. A shielded literal cannot be assigned to a regular type:

No immutable or constant. Shielded literals follow the same restriction as all shielded types — they cannot be used in immutable or constant declarations. See Footguns.

Compiler warning

All shielded literals emit warning 9660. This is intentional — literal values are embedded in the contract bytecode, which is publicly visible. The warning reminds you that the value is leaked at deployment time.

If the literal value is sensitive, do not hardcode it. Introduce it via encrypted calldata instead. See Footguns for more detail.

Clients

Overview

Seismic maintains client libraries for three languages.

TypeScript

seismic-viem

seismic-viem composes with viem to add Seismic transaction support, encrypted calldata, and signed reads. See the full documentation.

seismic-react

seismic-react composes with wagmi to provide React hooks for shielded reads, writes, and wallet management. See the full documentation.

Python — seismic-web3

seismic-web3 composes with web3.py to interact with Seismic nodes from Python. See the full documentation.

Rust — seismic-alloy

seismic-alloy composes with alloy to provide Seismic transaction types and encryption-aware providers. See the full documentation.

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

seismic-viem

Low-level SDK built on viem 2.x

Server-side, scripts, non-React apps

React hooks layer built on seismic-viem + wagmi

React applications

seismic-react depends on seismic-viem — install both if you're building a React app, or just seismic-viem for everything else.

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.

Property

Value

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.

Example

Description

Every example uses the same provider wrapper that combines RainbowKit, wagmi, and Seismic:

Footguns

Shielded types protect values at rest and in transit, but careless usage patterns can leak information through side channels. This page covers the most common information leak vectors when working with shielded types.

Conditional Execution

The problem: Using an sbool in a conditional branch leaks information through the execution trace and gas consumption. Observers can tell which branch was taken by examining the gas used or the operations performed.

// BAD: Leaks the value of `isVIP` via gas difference
sbool isVIP = /* ... */;
if (isVIP) {
    discount = 50s;
} else {
    // extra work only in the else branch — gas difference reveals which path ran
    suint256 tmp = 0s;
    for (uint256 i = 0; i < 10; i++) {
        tmp = tmp + 1s;
    }
    discount = tmp;
}

Why it leaks: The EVM execution trace shows which opcodes were executed. If the if branch runs different code (or a different amount of code) than the else branch, observers can determine which branch was taken, revealing the value of the shielded boolean.

What to do instead: Ensure both branches execute the same operations with the same gas cost. A ternary where both arms are simple assignments of the same type is safe — the EVM does the same work for both paths.

The problem: Assigning literal values to shielded types — whether via explicit cast or the — embeds those values directly in the contract bytecode, which is publicly visible.

What to do instead: Be aware that literals are embedded in contract bytecode and are publicly visible. The compiler emits warning 9660 for all shielded literals to remind you. If the initial value is sensitive, introduce it via encrypted calldata instead of hardcoding it.

The problem: Using a shielded value as a loop bound leaks the value through gas consumption. Each iteration costs gas, so the total gas used reveals how many times the loop executed.

Why it leaks: Gas is publicly visible. If a loop runs 5 times vs. 100 times, the gas difference is observable. This reveals the shielded loop bound.

What to do instead: Use a fixed-size loop with a known maximum, and perform no-op iterations when the actual count is smaller. The no-op path must cost the same gas as the real-work path — otherwise an observer can count how many iterations did real work by comparing per-iteration gas costs.

The problem: If you write a view function that unshields and returns private data without access control, anyone can read it. The shielded storage is meaningless if a public getter exposes the plaintext.

Why it leaks: The function casts the shielded value to a plain uint256 and returns it with no restriction on who can call it. The value is returned in plaintext to the caller.

What to do instead: Always add access control to view functions that unshield data. If the getter checks msg.sender, callers must use a — otherwise msg.sender will be the zero address.

The problem: Declaring a shielded variable as public will not compile. Solidity automatically generates a public getter for public state variables, which would return the shielded value -- violating the rule that shielded types cannot be returned from public or external functions.

What to do instead: Declare shielded variables as private or internal. If you need to expose the value, unshield it explicitly with a cast, and use access control (see above).

The problem: There is currently nothing enforcing that functions with shielded parameters are called via a Seismic transaction (type 0x4A). You can call a function that accepts suint256 with a regular transaction, and the shielded parameter values will be visible in plaintext in the transaction's input data. Likewise, you can use a Seismic transaction to call a function with no shielded inputs — the encryption is unnecessary but harmless.

What to do instead: If a function has any shielded inputs, always call it via a Seismic transaction. This is the caller's responsibility — the contract cannot currently enforce it. We plan to tighten this up in the future so the runtime rejects non-Seismic calls to functions with shielded parameters.

The problem: The ** operator has a gas cost that scales with the value of the exponent. If the exponent is a shielded value, the gas cost reveals the exponent.

Why it leaks: The EVM's modular exponentiation implementation uses more gas for larger exponents. An observer monitoring gas consumption can estimate the exponent value.

What to do instead: Avoid using shielded values as exponents entirely. If you need exponentiation with a private exponent, consider alternative algorithms and make sure you think carefully about their gas consumption profile.

The problem: Enum types have a small, known range of possible values. If you convert an enum to a shielded type, the limited range makes it easy to guess the shielded value — an observer only needs to try a handful of possibilities.

What to do instead: Consider whether the limited range of possible values undermines the privacy guarantee. Shielding an enum with 3 members is not meaningfully private.

The problem: Shielding hides a slot's value from RPC reads, but the value still participates in the storage Merkle trie that backs the account's storageHash. The trie key (the storage slot) is public, and the value is committed into the trie through a plain keccak hash with no per-slot salt. If a shielded value has low entropy — a boolean, a small enum, a value drawn from a known set — an attacker who knows the slot can guess candidate values, recompute the commitment, and confirm a match. The value is recovered without ever being read directly.

Why it leaks: A storage value enters the trie as roughly keccak256(RLP([slot_path, value])). With no salt, that commitment is a deterministic function of (slot, value), and the slot is known — so the only unknown is the value. The account's storageHash always exposes this commitment, but on its own it commits to the whole trie at once, so it is only practical to attack on freshly deployed or sparsely shielded contracts where the root covers just a handful of leaves.

Endpoints that return Merkle proofs (such as eth_getProof) make this much worse, and non-inclusion proofs are the sharpest case. A proof that a slot does not exist still returns the intermediate trie nodes along that slot's path. Because the trie key is keccak256(slot), an attacker can search for a junk, non-existent slot whose hash sits right next to your target's, request a non-inclusion proof for it, and pull back the branch node that directly commits to your private leaf. This isolates a single target leaf and makes it brute-forceable regardless of how full the trie is and without needing a conveniently located public slot nearby — defeating the intuition that a contract holding lots of shielded state is automatically safer. This is the same root cause as the footgun, generalized to any low-entropy value.

What to do instead: Do not rely on shielding alone to protect a low-entropy secret stored at a known slot. If a value is sensitive and has a small domain, mix in high entropy before storing it — for example store keccak256(abi.encode(secret, salt)), where salt is itself a high-entropy shielded value, and compare against that commitment rather than the raw secret. This only works for values you check by equality, not ones you do arithmetic on. High-entropy shielded values — balances that accumulate over many transactions, for instance — are not practically guessable and need no special handling.

Shielded types cannot be declared as immutable or constant. The compiler will reject both with an error. Constants are embedded in bytecode (publicly visible), and immutables are stored in bytecode after construction — neither is compatible with the confidential storage model.

What to do instead: Use a regular private shielded variable initialized in the constructor or via a setter function called through a Seismic transaction.

The problem: The synchronous produces randomness that is deterministic given the enclave's secret key, the transaction hash, remaining gas, and personalization bytes. In theory, a block proposer could simulate RNG outputs and selectively include, exclude, or reorder transactions to influence outcomes.

Why this matters: Seismic's TEE setup largely mitigates this — proposers are restricted in what they can observe and do, and we believe synchronous RNG is safe for most use cases. This is something we've thought about extensively. However, for applications with especially high-stakes randomness requirements, it's worth being aware of the theoretical attack surface.

What to do instead: For the most sensitive randomness use cases (large-pot lotteries, leader elections), consider using an asynchronous commit-reveal scheme where entropy is committed before the block in which it is consumed. Seismic does not provide this out of the box today. For the vast majority of use cases, the synchronous RNG precompile is appropriate.

The problem: A caller of a contract that uses the can revert their transaction if they don't like the outcome, giving them a risk-free way of interacting with your contract.

Why this matters: You should not use RNG precompile when the caller will be able to analayze the outcome and revert to undo

What to do instead: One example would be a poker contract where a dealer makes a call that uses RNG to shuffle the deck and set the state of it. After deck is shuffled players then can put in subsequent calls to deal from the shuffled deck but now they cannot revert to undo the state of the deck.

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

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.

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

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.

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.

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.

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.

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.

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

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.

The TEE (Trusted Execution Environment) is the foundation of Seismic's privacy model. Intel TDX provides the following guarantees:

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.

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.

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.

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.