SeismicElements

Seismic-specific transaction fields

Seismic-specific fields appended to every TxSeismic transaction.

Overview

SeismicElements contains the encryption parameters and block-expiry metadata required for all Seismic transactions. These fields enable calldata encryption and ensure transaction freshness.

Definition

@dataclass(frozen=True)
class SeismicElements:
    """Seismic-specific fields appended to a transaction.

    These fields are required for every TxSeismic and carry the
    encryption parameters plus block-expiry metadata.
    """
    encryption_pubkey: CompressedPublicKey
    encryption_nonce: EncryptionNonce
    message_version: int
    recent_block_hash: Bytes32
    expires_at_block: int
    signed_read: bool

Fields

Field	Type	Description
encryption_pubkey	CompressedPublicKey	Compressed secp256k1 public key for ECDH-derived calldata encryption
encryption_nonce	EncryptionNonce	12-byte AES-GCM nonce for encryption
message_version	int	Signing mode — 0 for raw, 2 for EIP-712
recent_block_hash	Bytes32	Hash of a recent block (freshness proof)
expires_at_block	int	Block number after which the transaction is invalid
signed_read	bool	True for signed eth_call reads, False for writes

Examples

Manual Construction

from seismic_web3 import (
    SeismicElements,
    CompressedPublicKey,
    EncryptionNonce,
    Bytes32,
)
import os

elements = SeismicElements(
    encryption_pubkey=CompressedPublicKey(...),  # From get_tee_public_key()
    encryption_nonce=EncryptionNonce(os.urandom(12)),
    message_version=2,  # EIP-712
    recent_block_hash=Bytes32(...),  # From w3.eth.get_block('latest')['hash']
    expires_at_block=12345678,  # Current block + 100
    signed_read=False,  # This is a write transaction
)

Typical Usage (SDK Handles This)

# SDK automatically constructs SeismicElements
result = await contract.write.transfer(recipient, amount)

# You don't need to build SeismicElements manually

With Custom Security Parameters

from seismic_web3 import SeismicSecurityParams, EncryptionNonce, Bytes32

# Override specific fields
security_params = SeismicSecurityParams(
    encryption_nonce=EncryptionNonce(...),
    recent_block_hash=Bytes32(...),
    expires_at_block=12345700,
    blocks_window=200,  # 200 blocks instead of default 100
)

# Pass to transaction method
result = await contract.write.transfer(
    recipient,
    amount,
    security_params=security_params,
)

Access from UnsignedSeismicTx

from seismic_web3 import UnsignedSeismicTx

unsigned_tx = UnsignedSeismicTx(...)

# Access SeismicElements
elements = unsigned_tx.seismic
print(f"Expires at block: {elements.expires_at_block}")
print(f"Signed read: {elements.signed_read}")

Field Details

encryption_pubkey

The TEE's compressed secp256k1 public key, obtained from w3.seismic.get_tee_public_key(). Used for ECDH key derivation to encrypt calldata.

encryption_nonce

A unique 12-byte nonce for AES-GCM encryption. Must never be reused with the same key. Auto-generated by the SDK if not specified.

message_version

Determines the signing method:

• 0 - Raw signing (RLP hash of unsigned transaction)

• 2 - EIP-712 typed data signing (structured, human-readable)

The SDK defaults to 2 (EIP-712) for better UX.

recent_block_hash

Hash of a recent block, proving the transaction was created recently. The node verifies this hash exists in the canonical chain. Auto-fetched by the SDK.

expires_at_block

Block number after which the transaction is considered invalid. Typically current_block + 100. Prevents replay attacks and ensures timely execution.

signed_read

• True - This is a signed eth_call (read-only, no state changes)

• False - This is a write transaction (will be broadcast)

Properties

• Immutable - Cannot be modified after construction (frozen=True)

• Required - All fields must be present for valid TxSeismic transactions

• Type-safe - All fields are validated at construction

Notes

• Automatically constructed by the SDK's write/read methods

• Can be customized via SeismicSecurityParams

• Part of the AAD (Additional Authenticated Data) for AES-GCM encryption

• Used in both UnsignedSeismicTx and TxSeismicMetadata

See Also

• SeismicSecurityParams - User-facing parameters to override defaults

• UnsignedSeismicTx - Contains SeismicElements

• TxSeismicMetadata - Uses SeismicElements for AAD

• CompressedPublicKey - Type for encryption_pubkey

• EncryptionNonce - Type for encryption_nonce

• Bytes32 - Type for recent_block_hash