This repository demonstrates the differences between standard ERC20 tokens and SRC20 (Seismic's confidential ERC20 variant) with private balances and encrypted transfer amounts.

packages/
├── contracts/           # Solidity contracts (SRC20 + ERC20)
├── listener-ts/
│   ├── src/erc20/       # ERC20 listener (standard viem)
│   └── src/src20/       # SRC20 listener (seismic-viem)
├── sender-ts/
│   ├── src/erc20/       # ERC20 sender (standard viem)
│   └── src/src20/       # SRC20 sender (seismic-viem)
└── listener-go/         # Go listener (SRC20 only)

Key difference: SRC20 events emit encrypted amounts with a key hash identifier, allowing only authorized parties to decrypt.

// ERC20: Standard viem
import { createWalletClient, createPublicClient, http } from "viem";
const walletClient = createWalletClient({ chain, account, transport: http() });
const publicClient = createPublicClient({ chain, transport: http() });

// SRC20: seismic-viem (async - performs key derivation)
import {
  createShieldedWalletClient,
  createShieldedPublicClient,
} from "seismic-viem";
const walletClient = await createShieldedWalletClient({
  chain,
  account,
  transport: http(),
});
const publicClient = createShieldedPublicClient({ chain, transport: http() });

// ERC20: Standard viem - amounts sent in PLAINTEXT
import { getContract } from "viem";
const contract = getContract({
  abi: ERC20Abi,
  address: contractAddress,
  client: { wallet: walletClient, public: publicClient },
});

// SRC20: seismic-viem - automatic encryption of suint256 params
import { getShieldedContract } from "seismic-viem";
const contract = getShieldedContract({
  abi: SRC20Abi,
  address: contractAddress,
  client: walletClient,
});

A key difference between ERC20 and SRC20 is how balances are read:

In Ethereum, anyone can make an eth_call and specify any from address to impersonate that account. On Seismic, this is blocked—any standard eth_call has its from address overridden to zero.

To read data that depends on msg.sender (like your private balance), use a Signed Read. This sends a signed message proving your identity, allowing the contract to return your private data.

import { signedReadContract } from "seismic-viem";

// SRC20: Read your own private balance (requires signature)
const myBalance = await signedReadContract(client, {
  abi: SRC20Abi,
  address: contractAddress,
  functionName: "balance",
  args: [],
});

Compare to ERC20 where anyone can read anyone's balance:

// ERC20: Read ANY address's balance (no signature needed)
const anyoneBalance = await client.readContract({
  abi: ERC20Abi,
  address: contractAddress,
  functionName: "balanceOf",
  args: [targetAddress], // Can be ANY address!
});

The listener periodically polls balances to demonstrate this difference. See listener.ts for the SRC20 implementation using signedReadContract.

seismic-viem provides two helper functions for watching SRC20 events with automatic decryption:

• watchSRC20Events: Automatically retrieves the user's AES key from the Directory contract via a signed read, then filters and decrypts events encrypted to that key. See usage in attachWalletEventListener.

• watchSRC20EventsWithKey: Takes an explicit viewing key as a parameter, acting as a "designated" event listener for that key. Useful when you have the AES key directly (e.g., intelligence providers). See usage in attachPublicEventListener.

When an SRC20 transfer or approval occurs, the contract emits multiple encrypted events:

1. To Intelligence Providers: The amount is encrypted to each registered intelligence provider's AES key
2. To the Recipient/Spender: The amount is encrypted to the recipient's (for transfers) or spender's (for approvals) registered AES key

┌─────────────────────────────────────────────────────────────────┐
│                     SRC20 Transfer Event                        │
├─────────────────────────────────────────────────────────────────┤
│  Event 1: Transfer(from, to, providerKeyHash, encryptedAmount)  │
│           └─ Decryptable by: Intelligence Provider              │
│                                                                 │
│  Event 2: Transfer(from, to, recipientKeyHash, encryptedAmount) │
│           └─ Decryptable by: Recipient only                     │
└─────────────────────────────────────────────────────────────────┘

SRC20 relies on two predeployed system contracts:

The Directory contract maintains a mapping of addresses to their AES encryption keys:

interface IDirectory {
    function checkHasKey(address _addr) external view returns (bool); // checks if an address has a key registered
    function keyHash(address to) external view returns (bytes32); // returns the hash for the key of an address
    function encrypt(address to, bytes memory _plaintext) external returns (bytes memory); // encrypts the plaintext using the key corresponding to the `to` address
    function setKey(suint256 _key) external;  // Register your AES key
}

Purpose: Allows users to register their AES keys so they can receive encrypted event data.

The Intelligence contract manages intelligence providers who can decrypt all transfer/approval amounts:

interface IIntelligence {
    function encryptToProviders(bytes memory _plaintext) external returns (bytes32[] memory, bytes[] memory); // encrypts data to all providers registered in the Intelligence contract
    function addProvider(address _provider) external; // adds a provider
    function removeProvider(address _provider) external; // removes a provider
    function numProviders() external view returns (uint256); // returns number of providers
}

Purpose: Intelligence providers (e.g., compliance services, analytics) can be granted access to decrypt all transaction amounts for regulatory or monitoring purposes.

You need our fork of the foundry development suite (sfoundry), specifically sforge, our tool to help build, test, deploy and debug Seismic smart contracts, to run contracts/, listener-ts, and sender-ts. See here for the installation command.

You then need to run bun install:all from the root to install all dependencies.

All packages read from a .env file in packages/contracts/. See packages/contracts/.env.example for the required variables.

cd packages/contracts
bash script/deploy.sh

This deploys both MockSRC20 and MockERC20 and writes their addresses to out/deploy.json.

bun run sender:src20

Output:

╔══════════════════════════════════════════════════════════════╗
║           SRC20 SENDER (seismic-viem)                        ║
║   All amounts are ENCRYPTED before sending                   ║
╚══════════════════════════════════════════════════════════════╝

bun run sender:erc20

Output:

╔══════════════════════════════════════════════════════════════╗
║           ERC20 SENDER (Standard viem)                       ║
║   All amounts are sent in PLAINTEXT                          ║
╚══════════════════════════════════════════════════════════════╝

bun run listener:src20

bun run listener:erc20

The sender scripts cycle through the following operations between Alice, Bob, and Charlie:

The SRC20 listener uses the encryptKeyHash field in events to filter and decrypt relevant transactions:

1. Compute key hash: The listener computes keccak256(AES_KEY) from your AES key
2. Filter events: Events are indexed by encryptKeyHash, so the listener only receives events encrypted to your key
3. Decrypt amount: The encryptedAmount is decrypted using your AES key via AesGcmCrypto

┌───────────────────────────────────────────────────────────────────┐
│                      SRC20 Listener Flow                          │
├───────────────────────────────────────────────────────────────────┤
│  1. AES_KEY (from .env) ──► keccak256() ──► keyHash               │
│     • INTELLIGENCE_AES_KEY for intelligence mode                  │
│     • RECIPIENT_AES_KEY for recipient mode                        │
│                                                                   │
│  2. watchEvent({ args: { encryptKeyHash: keyHash } })             │
│     └─ Only receives events where encryptKeyHash matches          │
│                                                                   │
│  3. For each matching event:                                      │
│     encryptedAmount ──► AesGcmCrypto.decrypt() ──► plaintext      │
└───────────────────────────────────────────────────────────────────┘

See listener.ts for the implementation.

bun run listener:src20
# or
cd packages/listener-ts && bun dev:src20 -- --intelligence

• Requires INTELLIGENCE_AES_KEY in .env
• Decrypts all transfer and approval amounts across all users

cd packages/listener-ts && bun dev:src20 -- --recipient

• Requires RECIPIENT_AES_KEY in .env (this will be Alice's AES encryption/decryption key since listener uses Alice's private key to initialize the shielded wallet client)
• Only decrypts transfers TO you and approvals FOR you as spender
• Prompts to register your key in the Directory if not already registered

For running without interactive prompts (e.g., with supervisor):

bun dev:src20 -- --recipient --no-prompt

cd packages/listener-go
go run ./

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[ERC20] Transfer - PLAINTEXT (visible to everyone on-chain)

    from: 0xAlice...
    to: 0xBob...
    amount: 42 (plaintext - NO encryption)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[Intelligence Provider] [SRC20] Transfer - ENCRYPTED (decrypted with AES key)

    from: 0xAlice...
    to: 0xBob...
    amount: 42 (decrypted from encrypted bytes)