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.

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.

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.

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

1. Download and execute the sfoundryup installation script.

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

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

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.

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.

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.

1. Navigate to the contracts subdirectory:

cd packages/contracts

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

1. Edit the .gitignore file to be the following:

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

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

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.

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.

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.

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 minor exceptions (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

Key differences

• 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

EVM Compatibility

Opcodes

• CLOAD – load shielded data from storage

• CSTORE – write shielded data to storage

• TIMESTAMP_MS – get the block timestamp in milliseconds. Note that block.timestamp still returns seconds, matching standard Solidity. Use block.timestamp_ms for millisecond precision

Seismic transaction

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)

Precompiles

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

• RNG 0x64 — securely generate a random number

• ECDH 0x65 — Elliptic Curve Diffie-Hellman, for generating a shared secret given a public key and secret key

• AES-GCM Encrypt 0x66 — encrypt data with AES-GCM

• AES-GCM Decrypt 0x67 — decrypt data with AES-GCM

• HKDF 0x68 — derive cryptographic keys from a parent key

• secp256k1 Sign 0x69 — sign a message given a secret key

Staking

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

Block times

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

RPC compatibility

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

Seismic-specific methods:

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

Modified Ethereum methods:

• eth_call — zeroes the from field on unsigned calls; supports "signed reads" via type 0x4A

• eth_sendRawTransaction — accepts Seismic transaction type 0x4A with encrypted calldata

• eth_getStorageAt — returns zero for shielded slots, making them indistinguishable from uninitialized storage

• Tracing endpoints are currently disabled. We plan to re-enable them with private data redacted from traces

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.

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

Pre-requisite knowledge

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

• Solidity

• Foundry

• Viem

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.

Seismic provides two TypeScript packages:

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

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.

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

1. Open the web app and connect MetaMask

2. Switch to the Seismic testnet (chain ID 5124)

3. Fill in the token name, symbol, and initial supply

4. Click Deploy and confirm the transaction in your wallet

5. The deployed token address and transaction hash appear on success

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.

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

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

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 Signed Reads for how those work.

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.

1. Navigate to the CLI subdirectory:

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

1. Initialize a new bun project

bun init -y

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

1. Now, edit package.json to be the following:

1. Edit .gitignore to be:

Your environment is now set!

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)

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:

1. chain: a well-defined Chain object

2. transport: the method of transport of interacting with the chain (http/ws along with the corresponding RPC URL)

3. privateKey: the private key to create the client for

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:

1. abi: the ABI of the contract it is interacting with.

2. address: the address of the deployed contract it is interacting with.

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

• Proxy-based access to dynamically invoke contract methods.

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

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.

Your client library (e.g., seismic-viem) handles Seismic transaction construction automatically when you use shielded write functions.

Be Mindful of Gas-Based Information Leakage

Gas consumption is publicly visible. Any operation whose gas cost depends on a shielded value is a potential leak. The main offenders are:

• Conditional branches on shielded booleans (different branches use different gas).

• Loops with shielded bounds (iteration count is visible via gas).

• Exponentiation with shielded exponents (gas scales with exponent value).

Use constant-time patterns: fixed-size loops, branchless logic, and avoid shielded exponents.

CLOAD and CSTORE themselves have constant gas cost by design -- the risk comes from higher-level patterns.

Use Casting Carefully

Every cast between shielded and unshielded types is a potential information leak. See Casting for details.

• Unshielded to shielded: The input value is visible in the trace.

• Shielded to unshielded: The output value is visible in the trace.

Minimize casts. During security review, identify every cast and confirm the exposure is intentional.

Review Compiler Warnings

The Seismic Solidity compiler generates a ton of warnings specific to shielded types. This is designed to be annoying because of how easy it is to make a mistake. Please review each warning carefully. These warnings flag potential privacy issues such as:

• Shielded values used in contexts that may leak information.

• Casts that expose confidential data.

• Patterns known to be risky.

Do not ignore these warnings. Treat them as seriously as you would treat security audit findings.

Test with sforge test

Use sforge test (the Seismic fork of Foundry's forge test) to run your test suite. It supports shielded types natively and can catch issues specific to confidential computation that standard forge test would miss.

Write tests that specifically verify:

• Shielded values remain confidential through the expected code paths.

• Access control prevents unauthorized reads of unshielded data.

Keep Shielded Data in the Shielded Domain

The longer a value stays shielded, the more private it is. Avoid unnecessary round-trips between shielded and unshielded types. Perform as much computation as possible in the shielded domain before unshielding a final result (if unshielding is even needed at all).

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.

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

Available Examples

Common Setup

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

Prerequisites

• Node.js 18+

• A WalletConnect project ID

• seismic-react and peer dependencies installed

See Also

• Hooks - Hook API reference

• Wallet Guides - RainbowKit, AppKit, and Privy integration

• Installation - Full dependency setup

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:

and add the following to it:

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

1. In a separate terminal window, run

in order to spin up a local Seismic node.

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

1. Now, from packages/contracts, deploy the contract:

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

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

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

Import

Usage

With RainbowKit

With wagmi Config

Notes

• Chain ID 5124 is used for EIP-155 replay protection and EIP-712 typed data signing

• The testnet supports all Seismic protocol features including shielded transactions and signed reads

• The Seismic icon is included automatically for display in RainbowKit's chain selector

See Also

• Chains Overview - All supported chains

• Sanvil - Local development chains

• createSeismicDevnet - Custom chain factory

• Wallet Guides - RainbowKit setup guides

Chain configuration for connecting to a locally-running Seismic Anvil (Sanvil) instance. sanvil is a RainbowKit-compatible chain object pre-configured for the default Sanvil endpoint.

Configuration

Import

Usage

With RainbowKit

With wagmi Config

localSeismicDevnet

localSeismicDevnet is a separate chain configuration for connecting to a locally-running seismic-reth node started in --dev mode. Use this instead of sanvil when you are running a full seismic-reth node locally rather than a Sanvil instance.

Installing Sanvil

Sanvil is part of the Seismic Foundry toolchain. Install it with sfoundryup:

Then start a local node:

By default, Sanvil:

• Listens on 127.0.0.1:8545

• Uses chain ID 31337

• Pre-funds test accounts with ETH

• Provides instant block mining

See Also

• Chains Overview - All supported chains

• Seismic Testnet - Public testnet configuration

• createSeismicDevnet - Custom chain factory

• Wallet Guides - RainbowKit setup guides

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

The Seismic Solidity compiler

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

suint256 balance = 100s;

the compiler emits CSTORE (opcode 0xB1) instead of SSTORE to write the value, and CLOAD (opcode 0xB0) instead of SLOAD to read it. These opcodes tell the EVM to treat the storage slot as private.

The supported shielded types are:

• suint / sint -- shielded integers (all standard bit widths: suint8 through suint256)

• sbool -- shielded boolean

• sbytes -- shielded bytes, both fixed-length (sbytes1 through sbytes32) and dynamic (sbytes)

• saddress -- shielded address

Arithmetic, comparisons, and assignments work exactly as they do with regular Solidity types. The compiler handles routing to the correct opcodes. You do not need to call any special APIs or change your contract logic.

The Seismic network

Seismic is an EVM-compatible L1 blockchain. Nodes run inside Trusted Execution Environments (TEEs) powered by Intel TDX. The TEE creates a hardware-enforced enclave: code and data inside the enclave cannot be observed or tampered with by the host operating system or the node operator.

Key network properties:

• Block time: Sub-second, powered by Summit (our custom consensus algorithm)

• Finality: 1 block

• Transaction types: All standard Ethereum types (Legacy, EIP-1559, EIP-2930, EIP-4844, EIP-7702) plus the Seismic transaction type 0x4A

The Seismic transaction (type 0x4A)

The diagram below shows the block structure, state tries, and the Seismic transaction format (TxSeismic). Note how each storage slot in the Account Storage trie carries a boolean flag -- (u256, true) for private slots and (u256, false) for public slots.

Standard Ethereum transactions send calldata in plaintext. The Seismic transaction type encrypts calldata before it leaves the user's machine.

The encryption flow:

1. The client calls seismic_getTeePublicKey on the RPC to fetch the network's TEE public key.

2. The client performs ECDH key agreement between the user's private key and the TEE public key to derive a shared secret.

3. The calldata is encrypted using AEAD (authenticated encryption with associated data).

4. The encrypted transaction is broadcast to the network.

5. Inside the TEE, the node decrypts the calldata, executes the transaction, and writes results to shielded storage.

At no point is the plaintext calldata visible outside the TEE -- not in the mempool, not in block data, not in transaction traces. For a deeper dive, see The Seismic Transaction.

Shielded storage (FlaggedStorage)

The diagram below shows how the RPC layer, EVM, and storage interact. Notice that eth_getStorageAt is blocked for shielded slots, and cross-contract reads of private storage return zero.

Seismic extends the EVM storage model with FlaggedStorage. Each storage slot is a tuple:

(value, is_private)

When a contract uses CSTORE to write a value, the is_private flag is set to true. This flag has two effects:

• eth_getStorageAt returns zero for shielded slots, making them indistinguishable from uninitialized storage. External observers cannot read or detect shielded data through the standard RPC.

• Only CLOAD can read private slots. The standard SLOAD opcode cannot access them. This is enforced in the Seismic EVM.

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:

mapping(address => suint256) balanceOf;

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

Step 1: User encrypts calldata. The client library (e.g., seismic-viem) fetches the TEE public key, derives a shared secret via ECDH, and encrypts the function and its arguments (to and amount) using AEAD. The encrypted payload is wrapped in a type 0x4A transaction.

Step 2: Transaction enters the mempool. The calldata is encrypted. Observers can see that a transaction was submitted to the SRC20 contract, but the recipient address and amount are not readable.

Step 3: Node decrypts inside the TEE. The Seismic node, running inside Intel TDX, decrypts the calldata using the network's private key. The plaintext arguments are now available only within the enclave.

Step 4: EVM executes with CSTORE. The EVM processes the transfer() function. Reads from balanceOf use CLOAD. Writes to balanceOf use CSTORE. These storage slots will have is_private = true.

Step 5: Storage is updated. The new balances are written to shielded storage.

Step 6: Observers see 0x00...0. Anyone querying the contract state, reading transaction traces, or inspecting block data sees zero in place of all shielded values -- the balances, the transfer amount, and any intermediate computation involving shielded types.

Precompiles

Seismic adds six precompiled contracts to the EVM, giving smart contracts access to cryptographic primitives that would be prohibitively expensive to implement in Solidity:

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:

All three components are designed so that private data is only ever accessible inside the Trusted Execution Environment. No plaintext shielded data leaves the TEE boundary at any point in the pipeline.

Seismic node

The Seismic node is a fork of reth (the Rust Ethereum execution client). It handles:

• RPC: Accepts incoming transactions and read requests. Serves responses to clients, redacting shielded data from public queries.

• EVM execution: Runs a modified EVM that supports CLOAD/CSTORE opcodes and the six Seismic precompiles. This is built on a forked version of revm.

• State management: Maintains the world state using FlaggedStorage, where each storage slot is tagged as public or private.

• Transaction pool: Receives both standard Ethereum transactions and Seismic transactions. Encrypted calldata in Seismic transactions is decrypted inside the TEE before execution.

The entire node process runs inside an Intel TDX Trusted Execution Environment. This means the node operator cannot inspect memory, attach debuggers, or extract keys from the running process.

Fork chain

The Seismic execution stack is built on a chain of forks from the Ethereum Rust ecosystem:

solidity  alloy-core  alloy-trie  revm  revm-inspectors  alloy-evm  reth   foundry  compilers  foundry-fork-db
   |          |           |         |         |              |        |        |         |            |
 ssolc   seismic-    seismic-  seismic-  seismic-revm-  seismic-  seismic- seismic- seismic-    seismic-
        alloy-core    trie       revm     inspectors      evm      reth   foundry  compilers  foundry-fork-db

• seismic-alloy-core (fork of alloy-core): Shielded types and FlaggedStorage primitives.

• seismic-trie (fork of alloy-trie): Merkle trie encoding for FlaggedStorage values.

• seismic-revm (fork of revm): CLOAD/CSTORE opcodes, Seismic precompiles, and FlaggedStorage access rules.

• (fork of revm-inspectors): EVM tracing/debugging with Seismic support.

• (fork of alloy-evm): Seismic block execution layer.

• (fork of reth): Full node with Enclave communication, modified RPC (redacting shielded data), and TEE attestation.

• (fork of solidity): Compiler adding shielded types (suint, sbool, sbytes, saddress).

• (fork of foundry): sforge, sanvil, scast dev tools.

• (fork of compilers): Compiler integration for sforge.

• (fork of foundry-fork-db): Fork DB with FlaggedStorage support.

Plus two original repos:

• summit: Consensus client.

• seismic-enclave: ECDH + AES-GCM crypto for transaction encryption/decryption.

• seismic-alloy: Rust SDK with TxSeismic type and encryption-aware providers.

For the full list and dependency flow, see Repos.

Summit (consensus)

Summit is Seismic's consensus layer, built on Commonware primitives. It handles:

• Block production: Ordering transactions into blocks with sub-second block times.

• Consensus: Reaching agreement among validators on the canonical chain.

• Finality: Single-block finality -- once a block is produced and agreed upon, it is final.

Summit communicates with the Seismic node to receive transactions from the mempool and to deliver finalized blocks for execution.

Enclave

The Enclave component manages all TEE-related operations. It is the trust anchor of the system.

Key management:

• Genesis node: When the network starts, the genesis node generates a root key inside the TEE. This key never leaves the enclave.

• Peer nodes: When a new node joins the network, it must pass remote attestation before receiving the root key. The existing nodes verify that the new node is running identical, approved code inside a genuine TEE.

• Encryption secret key: The root key is used to derive the network's encryption secret key. This key is used to decrypt the calldata of Seismic transactions (type 0x4A).

Attestation:

Remote attestation is the process by which one TEE proves to another that it is running approved code on genuine hardware. In Seismic:

1. A new node generates an attestation report inside its TEE.

2. The report is sent to existing nodes for verification.

3. Existing nodes check that the report was generated by genuine Intel TDX hardware and that the code measurement matches the approved build.

4. Only after successful verification does the new node receive the root key.

This ensures that every node in the network is running the same software and that no node can be modified to leak private data.

TEE guarantees

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

Code integrity

Remote attestation ensures that all nodes in the network are running identical, approved code. A node cannot be modified to log private data, skip encryption, or export keys.

Memory isolation

The TEE creates a hardware-enforced boundary around the node's memory. The host operating system, hypervisor, and node operator cannot read or write to the enclave's memory space.

Key protection

Cryptographic keys (the root key, encryption secret key, and any derived keys) are generated inside the TEE and never leave it. There is no API to export keys from the enclave. Even if the node operator has full root access to the host machine, they cannot extract the keys.

What TEEs do not protect against

• Side-channel attacks: While Intel TDX mitigates many known side-channel attacks, this is an active area of research. Seismic's design minimizes the attack surface, but hardware-level side channels remain a theoretical concern.

• Bugs in the node software: If the approved node code has a bug that leaks private data through a public channel (e.g., writing shielded values to public storage), the TEE will faithfully execute that buggy code. This is why the code is open-source and subject to audit.

• Transaction metadata: The TEE protects calldata and storage values, but metadata such as sender address, gas usage, and the target contract address remain visible on-chain.

• Low-entropy private storage values: Shielded storage hides values from RPC reads, but each value is still committed into the storage Merkle trie at a publicly known slot. A value with little entropy — a flag, a small enum — can be recovered by guessing candidates and checking them against the public trie commitment, without ever reading the slot. See for details and mitigations.

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.

suint256 reserve0;
suint256 reserve1;
mapping(address => suint256) liquidity;

function swap(address tokenIn, suint256 amountIn) internal returns (suint256 amountOut) {
    if (tokenIn == token0) {
        amountOut = (amountIn * reserve1) / (reserve0 + amountIn);
        reserve0 += amountIn;
        reserve1 -= amountOut;
    } else {
        amountOut = (amountIn * reserve0) / (reserve1 + amountIn);
        reserve1 += amountIn;
        reserve0 -= amountOut;
    }
}

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.

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

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

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, symbol

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

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.

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.

• Basic understanding of ERC20 -- You should know what balanceOf

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.

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.

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

A mapping that records every player's contribution to the current round, ensuring only participants can rob the clown's 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 using _randomIndex()

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]) by 1

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 sbytes to

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 enforce the rules of the game:

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

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

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

1. Create the project folder and navigate into it:

mkdir clown-beatdown
cd clown-beatdown

1. Create the packages directory with subdirectories for contracts and cli

mkdir -p packages/contracts packages/cli

The contracts subdirectory will house the Seismic smart contract(s) and test(s) for the project, while the cli will house the interface to interact with the contracts.

1. Initialize a bun project in the root directory:

We remove the default index.ts and tsconfig.json files created by bun init -y to keep the root directory clean and focused on managing the monorepo structure rather than containing code. We also create a .prettierrc file for consistent code formatting and a .gitmodules file to manage contract submodules.

1. Replace the default package.json with the following content for a monorepo setup:

1. Add the following to the .prettierrc file for consistent code formatting:

1. Replace the .gitignore file with:

1. Add the following to the .gitmodules file to track git submodules (in our case, only the Forge standard library, forge-std):

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:

mkdir -p packages/cli/lib
touch packages/cli/lib/constants.ts packages/cli/lib/utils.ts
cd packages/cli/lib

constants.ts will contain the constants we use throughout the project while utils.ts will contain the necessary utility functions.

Add the following to constants.ts:

This file centralizes key project constants:

• CONTRACT_NAME: The ClownBeatdown contract name.

• CONTRACT_DIR: Path to the contracts directory.

Now, add the following to utils.ts:

This file contains utility functions to interact with your ClownBeatdown contract:

• getShieldedContractWithCheck: Ensures the contract is deployed and returns a shielded contract instance.

• readContractAddress: Reads the deployed contract's address from a broadcast file.

• readContractABI: Parses the contract's ABI from an ABI file for use in interactions.

Operations on shielded types return shielded types. For example, comparing two suint256 values produces an sbool, not a bool. Arithmetic on sint256 returns sint256, and so on.

Shielded Integers

All comparisons and operators for shielded integers are functionally identical to their unshielded counterparts.

suint - Shielded Unsigned Integer

suint256 a = suint256(10);
suint256 b = suint256(3);

// == EXAMPLES
a > b   // sbool(true)
a | b   // suint256(11)
a << 2  // suint256(40)
a % b   // suint256(1)

sint - Shielded Signed Integer

sint256 a = sint256(-10);
sint256 b = sint256(3);

// == EXAMPLES
a < b   // sbool(true)
a + b   // sint256(-7)
a * b   // sint256(-30)

sbool - Shielded Boolean

All comparisons and operators for sbool function identically to bool.

We recommend reading the point on prior to using sbool since it's easy to accidentally leak information with this type.

An saddress variable supports code and codehash members only. Members like call, delegatecall, staticcall, balance, and transfer are not available — you must cast to address first.

Fixed-size shielded bytes mirror the standard bytes1–bytes32 types.

Dynamic shielded bytes mirror the standard bytes type. The length is stored as shielded — like , observers cannot read it directly but may infer an upper bound from gas costs.

You can create shielded integer constants with either an explicit cast or the s suffix:

The s suffix infers the shielded type from context and works with hex, underscores, scientific notation, and unary minus. See for the full specification.

seismic-react integrates with any wallet library that provides wagmi configuration. This section covers setup for the most popular options.

Supported Libraries

Regardless of which wallet library you choose, the integration follows the same steps:

1. Install the wallet library alongside seismic-react

2. Configure wagmi with Seismic chain definitions

3. Nest providers in the correct order

4. Use hooks from

All wallet integrations require the same provider hierarchy:

All wallet libraries use the same chain imports from seismic-react/rainbowkit:

• Want the easiest setup with a beautiful wallet modal? Use

• Need email/social login or embedded wallets? Use

• Want WalletConnect with maximum wallet compatibility? Use

• -- Package setup and peer dependencies

• -- Provider reference and configuration

• -- All available hooks

Factory function that creates a RainbowKit-compatible chain configuration for any Seismic node. Use this when the pre-configured chains (seismicTestnet, sanvil, localSeismicDevnet) do not match your node's host.

Import

import { createSeismicDevnet } from "seismic-react/rainbowkit";

Parameters

RainbowKitChain -- a chain object compatible with RainbowKit's getDefaultConfig and wagmi's createConfig.

The returned chain has:

• Chain ID: 5124

• Name: Seismic

• Native Currency: ETH (18 decimals)

• The nodeHost parameter should be the bare hostname without a protocol prefix or path. HTTPS and WSS URLs are constructed automatically.

• The Seismic icon is included automatically for display in RainbowKit's chain selector.

• The underlying implementation delegates to createSeismicDevnet from seismic-viem and wraps the result with RainbowKit metadata.

• - All supported chains

• - Public testnet configuration

• - Local development chains

• - RainbowKit setup guides

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.

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

Example output:

Pre-deployed on Seismic testnet at 0x87F850cbC2cFfac086F20d0d7307E12d06fA2127.

Deploys a new SRC20Token, records it in the tokens array, emits TokenCreated, and returns the deployed address. The caller becomes the token's owner.

initialSupply is a suint256 — it is encrypted in the transaction and never visible on-chain. The supply is minted directly to msg.sender

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.

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:

1. Shielded types cannot be

In this chapter, you'll write the core logic to interact with the ClownBeatdown contract by creating an App class. This class will initialize player-specific wallet clients and contracts, and provide easy-to-use functions like hit, rob, and reset. Estimated time: ~20 minutes

Now, navigate to packages/cli/src/ and create a file called app.ts which will contain the core logic for the CLI:

Start by importing all the necessary modules and functions at the top of app.ts:

The AppConfig interface organizes all settings for the Clown Beatdown app, including player info, wallet setup, and contract details. It supports a multiplayer environment, with multiple players having distinct private keys and contract interactions.

The App

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.

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

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.

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

SRC20 is Seismic's confidential token standard. Transfer and approval amounts are encrypted in the event log, so standard event watchers see only ciphertext. seismic-viem ships two client extensions that filter these events and decrypt the amounts for you:

• src20WalletActions.watchSRC20Events -- wallet-client action that fetches the viewing key for the connected address from the Directory contract via a signed read, then watches and decrypts events the wallet can read.

• src20PublicActions.watchSRC20EventsWithKey -- public-client action that takes an explicit AES viewing key. Useful for server-side monitoring, intelligence providers, or any flow without a connected wallet.

seismic-react provides four hooks that mirror wagmi's hook API but route through Seismic's shielded transport layer. Each hook wraps the corresponding seismic-viem client or contract method, handling encryption, signing, and decryption automatically.

seismic-react provides pre-configured chain objects compatible with RainbowKit's getDefaultConfig. Each chain wraps a chain definition with RainbowKit metadata (icon, etc.).