SRC20_ABI

SRC20 token standard ABI constant

ABI definition for Seismic's privacy-preserving SRC20 token standard.

Overview

SRC20_ABI is a Python list containing the complete ABI for the ISRC20 interface, which defines Seismic's privacy-preserving ERC20-compatible token standard. Unlike standard ERC20, SRC20 uses shielded types (suint256) for amounts to preserve balance and transfer privacy.

The SRC20 standard maintains the familiar ERC20 API while adding privacy features:

Token amounts are shielded using suint256 types
balanceOf() takes no arguments and returns the caller's own balance
Transfer and approval events emit encrypted amounts

Import

from seismic_web3 import SRC20_ABI

Type

SRC20_ABI: list[dict[str, Any]]

ABI Contents

The ABI includes the following functions and events:

Functions

Function

Parameters

Returns

Description

name()

None

string

Token name (view)

symbol()

None

string

Token symbol (view)

decimals()

None

uint8

Token decimals (view)

balanceOf()

None

uint256

Caller's token balance (view)

approve(address, suint256)

spender, amount

bool

Approve spender for shielded amount

transfer(address, suint256)

to, amount

bool

Transfer shielded amount to recipient

transferFrom(address, address, suint256)

from, to, amount

bool

Transfer shielded amount from approved account

Events

Event

Parameters

Description

Transfer

from (indexed), to (indexed), encryptKeyHash (indexed), encryptedAmount

Emitted on transfer with encrypted amount

Approval

owner (indexed), spender (indexed), encryptKeyHash (indexed), encryptedAmount

Emitted on approval with encrypted amount

Full ABI

SRC20_ABI: list[dict[str, Any]] = [
    {
        "type": "function",
        "name": "name",
        "inputs": [],
        "outputs": [{"name": "", "type": "string", "internalType": "string"}],
        "stateMutability": "view",
    },
    {
        "type": "function",
        "name": "symbol",
        "inputs": [],
        "outputs": [{"name": "", "type": "string", "internalType": "string"}],
        "stateMutability": "view",
    },
    {
        "type": "function",
        "name": "decimals",
        "inputs": [],
        "outputs": [{"name": "", "type": "uint8", "internalType": "uint8"}],
        "stateMutability": "view",
    },
    {
        "type": "function",
        "name": "balanceOf",
        "inputs": [],
        "outputs": [{"name": "", "type": "uint256", "internalType": "uint256"}],
        "stateMutability": "view",
    },
    {
        "type": "function",
        "name": "approve",
        "inputs": [
            {"name": "spender", "type": "address", "internalType": "address"},
            {"name": "amount", "type": "suint256", "internalType": "suint256"},
        ],
        "outputs": [{"name": "", "type": "bool", "internalType": "bool"}],
        "stateMutability": "nonpayable",
    },
    {
        "type": "function",
        "name": "transfer",
        "inputs": [
            {"name": "to", "type": "address", "internalType": "address"},
            {"name": "amount", "type": "suint256", "internalType": "suint256"},
        ],
        "outputs": [{"name": "", "type": "bool", "internalType": "bool"}],
        "stateMutability": "nonpayable",
    },
    {
        "type": "function",
        "name": "transferFrom",
        "inputs": [
            {"name": "from", "type": "address", "internalType": "address"},
            {"name": "to", "type": "address", "internalType": "address"},
            {"name": "amount", "type": "suint256", "internalType": "suint256"},
        ],
        "outputs": [{"name": "", "type": "bool", "internalType": "bool"}],
        "stateMutability": "nonpayable",
    },
    {
        "type": "event",
        "name": "Transfer",
        "inputs": [
            {
                "name": "from",
                "type": "address",
                "indexed": True,
                "internalType": "address",
            },
            {
                "name": "to",
                "type": "address",
                "indexed": True,
                "internalType": "address",
            },
            {
                "name": "encryptKeyHash",
                "type": "bytes32",
                "indexed": True,
                "internalType": "bytes32",
            },
            {
                "name": "encryptedAmount",
                "type": "bytes",
                "indexed": False,
                "internalType": "bytes",
            },
        ],
        "anonymous": False,
    },
    {
        "type": "event",
        "name": "Approval",
        "inputs": [
            {
                "name": "owner",
                "type": "address",
                "indexed": True,
                "internalType": "address",
            },
            {
                "name": "spender",
                "type": "address",
                "indexed": True,
                "internalType": "address",
            },
            {
                "name": "encryptKeyHash",
                "type": "bytes32",
                "indexed": True,
                "internalType": "bytes32",
            },
            {
                "name": "encryptedAmount",
                "type": "bytes",
                "indexed": False,
                "internalType": "bytes",
            },
        ],
        "anonymous": False,
    },
]

Usage Examples

Creating a Contract Instance

from seismic_web3 import create_wallet_client, SRC20_ABI

# Create client
w3 = create_wallet_client(
    rpc_url="https://gcp-1.seismictest.net/rpc",
    private_key="0x...",
)

# Create contract instance
token = w3.seismic.contract(
    address="0x1234567890123456789012345678901234567890",
    abi=SRC20_ABI,
)

Reading Token Metadata

# Get token name, symbol, and decimals (transparent reads)
name = token.tread.name()
symbol = token.tread.symbol()
decimals = token.tread.decimals()

print(f"Token: {name} ({symbol})")
print(f"Decimals: {decimals}")

Checking Balance

# Get caller's balance (signed read - proves your identity)
balance = token.read.balanceOf()

from eth_abi import decode
balance_value = decode(['uint256'], balance)[0]
print(f"Balance: {balance_value}")

Transferring Tokens

from seismic_web3 import Suint256

# Transfer 100 tokens (with 18 decimals)
recipient = "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"
amount = Suint256(100 * 10**18)

tx_hash = token.write.transfer(recipient, amount)
print(f"Transfer tx: {tx_hash.hex()}")

Approving Spender

from seismic_web3 import Suint256

# Approve spender for 1000 tokens
spender = "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"
amount = Suint256(1000 * 10**18)

tx_hash = token.write.approve(spender, amount)
print(f"Approval tx: {tx_hash.hex()}")

Using transferFrom

from seismic_web3 import Suint256

# Transfer from approved account
owner = "0x5B38Da6a701c568545dCfcB03FcB875f56beddC4"
recipient = "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"
amount = Suint256(50 * 10**18)

tx_hash = token.write.transferFrom(owner, recipient, amount)
print(f"TransferFrom tx: {tx_hash.hex()}")

Listening to Transfer Events

# Get recent transfer events
events = token.events.Transfer.get_logs(from_block="latest" - 1000)

for event in events:
    print(f"Transfer from {event.args['from']} to {event.args['to']}")
    print(f"Encrypted amount: {event.args['encryptedAmount'].hex()}")
    print(f"Key hash: {event.args['encryptKeyHash'].hex()}")

When to Use

Use SRC20_ABI when:

Interacting with SRC20-compliant privacy tokens
Building DeFi applications with shielded balances
Deploying privacy-preserving token contracts
Creating token swap or exchange interfaces
Implementing token approval flows with privacy

Key Differences from ERC20

balanceOf() Takes No Arguments

Standard ERC20:

function balanceOf(address account) external view returns (uint256);

SRC20:

function balanceOf() external view returns (uint256);

In SRC20, balanceOf() always returns the caller's balance. Use signed reads (.read) to prove your identity.

Shielded Amounts

All amounts are suint256 (shielded uint256) instead of plain uint256:

# Use Suint256 wrapper for shielded amounts
from seismic_web3 import Suint256

amount = Suint256(100 * 10**18)  # 100 tokens
token.write.transfer(recipient, amount)

Encrypted Events

Events include encryption metadata:

encryptKeyHash - Hash of the encryption key used
encryptedAmount - AES-GCM encrypted amount

To decrypt events, you need access to the viewing key registered in the Directory contract.

Privacy Features

What Gets Encrypted

Token amounts in all operations (transfer, approve, etc.)
Event amounts (encrypted before emission)

What Remains Visible

Token metadata (name, symbol, decimals)
Participant addresses (from, to, spender)
Transaction existence and timing
Function being called

Viewing Keys

Users must register viewing keys in the Directory contract to decrypt their balances and amounts:

from seismic_web3 import DIRECTORY_ABI, DIRECTORY_ADDRESS, Suint256

# Register viewing key
directory = w3.eth.contract(address=DIRECTORY_ADDRESS, abi=DIRECTORY_ABI)

viewing_key = Suint256(...)  # Your AES-256 key as suint256
tx_hash = directory.functions.setKey(viewing_key).transact()

Contract Source

This ABI matches the ISRC20 interface defined in:

contracts/src/seismic-std-lib/SRC20.sol

hashtagOverview

hashtagImport

hashtagType

hashtagABI Contents

hashtagFunctions

hashtagEvents

hashtagFull ABI

hashtagUsage Examples

hashtagCreating a Contract Instance

hashtagReading Token Metadata

hashtagChecking Balance

hashtagTransferring Tokens

hashtagApproving Spender

hashtagUsing transferFrom

hashtagListening to Transfer Events

hashtagWhen to Use

hashtagKey Differences from ERC20

hashtagbalanceOf() Takes No Arguments

hashtagShielded Amounts

hashtagEncrypted Events

hashtagPrivacy Features

hashtagWhat Gets Encrypted

hashtagWhat Remains Visible

hashtagViewing Keys

hashtagContract Source

hashtagSee Also

Overview

Import

Type

ABI Contents

Functions

Events

Full ABI

Usage Examples

Creating a Contract Instance

Reading Token Metadata

Checking Balance

Transferring Tokens

Approving Spender

Using transferFrom

Listening to Transfer Events

When to Use

Key Differences from ERC20

balanceOf() Takes No Arguments

Shielded Amounts

Encrypted Events

Privacy Features

What Gets Encrypted

What Remains Visible

Viewing Keys

Contract Source

See Also