In this chapter, you’ll set up the foundation for the Walnut App 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.

System requirements

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

• x84_64 or arm64 architecture

• MacOS, Ubuntu, or Windows

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 and 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 (or 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.

What is Seismic?

Seismic is a privacy enabled blockchain for fintechs. The blockchain is EVM, so developer experience is approximately the same as Ethereum, with a bit of extra syntax to control privacy settings.

It also comes with additional modules commonly needed by fintechs, such as compliance tooling and on-/off-ramps.

Whether you're an individual developer or part of a larger team, Seismic can help you build crypto powered products while protecting the privacy of your users.

How to use the docs

The docs are organized into 4 sections:

• : You are here.

• : Shortcut to getting your hands dirty.

• : Walkthrough of core concepts for developing on Seismic.

• : Detailed technical references.

Use the sidebar to navigate through the sections, or search (Cmd+K) to quickly find a page.

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

Work with us

If you might benefit from direct support from the team, please don't hesitate to reach out to [email protected]. We pride ourselves in fast response time.

You can also check out our for the latest updates.

You can play around with stype using our . This assumes you went through everything in .

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.

An saddress variable has all address operations supported. As for members, it supports call, delegatecall, staticcall, code, and codehash only. You cannot have saddress payable or have saddress as a transaction signer.

The universal casting rules and restrictions described in Basics apply.

saddress a = saddress(0x123);
saddress b = saddress(0x456);

// == VALID EXAMPLES
a == b  // false
b.call()

// == INVALID EXAMPLES
a.balance
payable(a)

This section dives into the heart of the Walnut App—the shielded smart contract that powers its functionality. You’ll start by building the foundational pieces of the Walnut, including the kernel and the protective shell, before implementing more advanced features like rounds, reset mechanisms, and contributor-based access control. By the end of this section, you’ll have a fully functional, round-based Walnut contract that is secure, fair, and replayable.

What You'll Learn

In this section, you’ll:

• Define and initialize the kernel, the hidden value inside the Walnut.

• Build the shell, the protective layer that hides the kernel, and implement a hit()

Typescript

Seismic maintains , which composes with to make calls to an RPC provider

The documentation for seismic-viem can be found

All comparisons and operators for suint / sint are functionally identical to uint / int. The universal casting rules and restrictions described in Basics apply.

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

// == EXAMPLES
a > b  // true
a | b  // 11
a << 2  // 40
a % b  // 1

1. Navigate to the contracts subdirectory:

cd packages/contracts

1. Initialize a project with sforge :

sforge init --no-commit && rm -rf .github

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 Walnut counterparts (Walnut.sol , Walnut.t.sol and Walnut.s.sol ):

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

Network configuration

Explorer

Currently in development

Faucet

We will host a faucet at

If you are a third party working with us, please send us an address. We will make sure it is always topped up

1. Create the project folder and navigate into it:

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

The contracts

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 contracts subdirectory:

1. Initialize a new bun project

You can find our deploy tools

Documentation for these tools will be published here soon

All comparisons and operators for sbool function identically to bool. The universal casting rules and restrictions described in apply.

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

In this section, you will write a CLI to interact with the deployed Walnut 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

In this chapter, you’ll deploy your Walnut 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 Walnut App and open the Walnut.s.sol file located at:

packages/contracts/script

and add the following to it:

This script will deploy a new instance of the Walnut contract with an initial shell strength of 3 and an initial kernel value of 0.

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 nine standard sanvil testing private keys.

1. Now, from packages/contracts, run

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

In this chapter, you’ll learn to create and initialize the kernel, a hidden value inside the Walnut, and increment it by implementing a shake function. Estimated time: ~10 minutes.

Defining the kernel

The kernel is the hidden number inside the Walnut. Using Seismic’s suint256 type, the kernel is shielded on-chain. Open up packages/contracts/Walnut.sol and define the kernel as a state variable and initialize it in the constructor:

Add a shake function

In this chapter, you’ll write the core logic to interact with the Walnut contract by creating an App class. This class will initialize player-specific wallet clients and contracts, and provide easy-to-use functions like hit, shake, reset, and look. 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:

Import required dependencies

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

Define the app configuration

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

Create the App class

The App class manages player-specific wallet clients and contract instances, providing an easy-to-use interface for multiplayer gameplay.

Add initialization logic to App

The init()method sets up individual wallet clients and contract instances for each player, enabling multiplayer interactions. Each player gets their own wallet client and a direct connection to the contract.

Add helper methods to App

These helper methods ensure that the app fetches the correct wallet client or contract instance for a specific player, supporting multiplayer scenarios.

getWalletClient :

getPlayerContract :

Implement Contract Interaction Methods

reset

Resets the Walnut for the next round. The reset is player-specific and resets the shell and kernel values.

shake

Allows a player to shake the Walnut, incrementing the kernel. This supports multiplayer scenarios where each player’s shakes impact the Walnut. Uses signed writes.

hit :

A player can hit the Walnut to reduce the shell’s strength. Each hit is logged for the respective player.

look :

Reveals the kernel for a specific player if they contributed to cracking the shell. This ensures fairness in multiplayer gameplay. Uses signed reads.

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

• RPC methods are identical to reth

• Standard Solidity bytecode will behave identically on Seismic

• Seismic supports all of Ethereum's opcodes & precompiles

• Transaction priority & fees follow EIP-1559 rules

• 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

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 cryptography

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 see timestamps in milliseconds

• All RPC endpoints will format block timestamps in seconds for Ethereum compatibility (not ms)

• In Seismic Solidity, block.timestamp returns unix seconds, just like in standard solidity. We added block.timestamp_ms which returns unix milliseconds

RPC compatibility

We support almost every RPC endpoint in Reth, and have added a few more of our own

These methods are in Reth, but will behave differently on Seismic:

• Calls to tracing endpoints will remove shielded data from the trace

• Calls to getStorageAt will fail if the requested storage slot holds shielded data

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

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 the 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 shake ) and shielded reads (for look()) in our CLI.

All stype variables can be stored in Solidity collections, much like their unshielded counterparts. They behave normally (as outlined in Basics) when used as values in these collections. It's when they're used as both the keys and values where it gets interesting. This applies to arrays and maps in particular:

suint256[] a;  // stype as value
function f(suint256 idx) {
    a[idx]  // stype as key
    // ...
}

// ==========

mapping(saddress => suint256) m;  // stype as key and value
function d(suint256 k) {
    m[k]
}

What's special here is that you can hold on to a[idx] and m[k] without observers knowing which values in the collection they refer to. You can read from these references:

sbool b = a[idx] < 10;
suint256 s = m[k] + 10;

You can write to these references:

a[idx] *= 3;
m[k] += a[idx];

Observers for any of these operations will not know which elements were read from / written to.

In the previous section, we only knew how to shield what was happening for certain elements. Now, we know how to shield which elements are being modified in the first place.

We can take the ERC20 variant discussed in the section and extend it further to shielded balances, transfer amounts, and now recipients.

In this chapter, you will learn about defining and 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/cliwith 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 with utils.ts will contain the necessary utility functions.

Add the following to constants.ts :

This file centralizes key project constants:

• CONTRACT_NAME: The Walnut 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 Walnut 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.

Official channels

• X.com/SeismicSys

• Join our Discord

Links

• Seismic

• documentation

• Seismic solidity extensions

Contact

For partnerships, contact L@, T@ or M@ seismic (dot) systems

If you would like to work at Seismic, email your resume to M@

In this chapter, you’ll write tests to verify that the Walnut contract behaves as expected under various scenarios. Testing ensures the functionality, fairness, and access control mechanisms of your contract work seamlessly, particularly in multi-round gameplay. Estimated Time: ~15 minutes.

Getting Started

Navigate to the test folder in your Walnut App and open the Walnut.t.sol file located at:

This file is where you’ll write all the test cases for the Walnut contract. Start with the following base code:

The setUp()

Now that we’ve built the core logic for interacting with the Walnut contract, it’s time to tie everything together into a CLI that runs a multiplayer game session with two players - Alice and Bob. In this chapter, you’ll set up the environment variables for multiple players and write index.ts to simulate gameplay. Estimated time: ~20 minutes

Set Up Environment Variables

Before running the Walnut game, we need to define environment variables that store important configurations such as the RPC URL, chain ID, and player private keys.

Create a .env in

Mental model

Developers communicate to Seismic through the stype. A thorough understanding of this one concept unlocks all shielded computation and storage. The

Imagine you’re holding a walnut, an unassuming object. Inside it lies a number, a secret only revealed when you crack the shell. There are primarily two actions you can take on this walnut: either shaking it or hitting it. Shaking the walnut some n number of times increments the number inside by n, while hitting the walnut brings it one step closer to the shell cracking. You can only see the number inside if you have contributed to the cracking the shell, i.e., you have hit the walnut at least once. This collaborative challenge is the heart of the Walnut App, and it’s all powered by the Walnut 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 packages/contracts/Walnut.sol file of the starter repo.

State variables

startShell and shell

Think of the shell as the Walnut’s durability. startShell is the Walnut’s starting strength, and shell tracks how much of it remains as players hit it.

startNumber and number

These are the secret numbers at the heart of the Walnut. startNumber initializes the hidden number, while number evolves as players shake the Walnut. Being suint256 (shielded integers), these numbers remain encrypted on-chain—visible only to authorized participants.

round

A counter that increments with each new round/reset, ensuring every round has a fresh Walnut to crack.

hitsPerRound

A mapping that records every player’s contribution to the current round, ensuring only participants can peek at the Walnut’s secret.

Functions

hit ( )

This function allows a player to hit the Walnut, reducing its durability and bringing it one step closer to cracking:

What happens:

• Checks if the shell is intact (shell>0 )

• If it is, decrements shell by 1

• Increases the player who called hit() 's contribution in the current round (hitsPerRound[round][playerAddress]) by 1

shake (suint256 _numShakes)

This function allows a player to shake the walnut _numShakes number of times. Since this is a write function that takes in an stype as one of its parameters, calling this function would constitute a Seismic write.

What happens:

• Adds _numShakes to number

• Emits the Shake event.

look ( )

This function allows contributors to the current round to view the number inside the walnut. Since this is a view function that reveals an stype, calling this function would constitute a Seismic read.

What happens:

• Requires the shell to be cracked (requireCracked modifier)

• Ensures the function caller contributed to the cracking the walnut for this round (onlyContributor modifier)

• Returns ("reveals") the number inside the walnut.

Modifiers

Modifiers enforce the rules of the game:

requireCracked

Ensures that look() can only be called if the Walnut’s shell is completely cracked.

requireIntact

Ensures that shake() and hit() can only be called if the Walnut’s shell is intact.

onlyContributor

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

Our consensus client. Built on top of

Welcome! This walkthrough is quick. It only requires a minute of actual attention, while the rest is waiting. If you run into any issues, please check if it's one of the 10 common errors resolved in the section. You can also hop in and ask questions in the #devnet channel.

If you end up deploying your own custom contract, please send the github link to on TG! Also note, this is not an incentivized testnet.

Works on Mac, Linux, and Windows via WSL (see ).

In this chapter, you’ll build the shell, the protective layer that hides the kernel. You’ll initialize the shell’s strength and implement a hit function to decrement it. Additionally, you’ll add a look() function with a requiredCracked modifier to ensure the kernel can only be viewed once the shell is fully broken. Estimated Time: ~10 minutes.

Defining the shell

The shell determines the Walnut’s resilience. It has an integer strength (shellStrength

General

Seismic nodes have to run inside a TEE. Why? and what does that mean for node operators?

Seismic nodes run inside TEEs so we can verify that they are running the correct software via remote attestation. If someone were to deploy a node that allowed them to view network secrets, it would be rejected by other nodes, and therefore never receive any sensitive data.

In this chapter, we’ll implement a reset mechanism that allows the Walnut to be reused in multiple rounds, ensuring each game session starts fresh. We’ll also track contributors per round so that only players who participated in cracking the Walnut can call look(). By the end, we’ll have a fully functional round-based walnut game where the kernel remains shielded until conditions are met! Estimated time: ~15 minutes.

The need for a Reset mechanism

Right now, once the Walnut is cracked, there’s no way to reset it. If a game session were to continue, we’d have no way to start fresh—the shell would remain at 0, and the kernel would be permanently revealed.

To solve this, we need to introduce:

✅ A reset function that restores the Walnut to its original state.

✅ Round tracking, so each reset creates a new round.

The need for a contributor check

While the reset mechanism and round tracking allow us to restart the Walnut for continuous gameplay, they still don’t address who should be allowed to call the look() function.

Right now, any player can call look() once the shell is cracked, even if they didn’t participate in hitting it during the current round. This creates the following issues:

• Fairness: Players who didn’t contribute should not be able to reap the benefits of seeing the kernel.

• Incentivizing Contribution: The game needs to encourage active participation by ensuring that only those who helped crack the Walnut in a specific round are rewarded with access to the kernel.

The solution to this is implementing a conditional check on look() which allows only those players who contributed in hitting the shell for a particular round (i.e., players whose hit count is >0 for that round) to view the kernel after the walnut is cracked.

Implementing the Reset Mechanism

The reset mechanism allows the Walnut to be reused for multiple rounds, with each round starting fresh. It restores the Walnut’s shell and kernel to their original states and increments the round counter to mark the beginning of a new round.

Here’s how we can implement the reset function:

What’s Happening Here?

• Condition for Reset (requireCracked): The reset function can only be called once the Walnut’s shell is cracked, enforced by the requireCracked modifier.

• Restoring Initial State: The shell strength and kernel are reset to their original values (initialShellStrength and initialKernel), ensuring the Walnut starts afresh for the next round.

Modifying hit() to track contributions

To enforce fair access to the kernel, we’ll track the number of hits each player contributes in a given round. This is achieved using the hitsPerRound mapping:

Every time a player calls the hit() function, we update their contribution in the current round:

What’s Happening Here?

• Tracking Contributions: The hitsPerRound mapping records each player’s hits in the current round. This ensures we can verify who participated when the Walnut was cracked.

• Replayable Rounds: Because contributions are tracked by round, the game can fairly reset and start fresh without losing player data from previous rounds.

Restricting look() with a contributor check

To ensure only contributors can reveal the kernel, we’ll use a modifier called onlyContributor:

We’ll then apply this modifier to the look() function:

Congratulations! You made it through to writing the entire shielded smart contract for a multiplayer, multi-round, walnut app!

Final Walnut contract

Now, onto testing the contract!

Network Configuration

Genesis date

The mainnet genesis date will be announced publicly. Follow official channels for updates:

Explorer

Currently in development

Contract verification

The explorer will support the ability to verify contracts written in Seismic Solidity