Encryption

TEE key exchange, ECDH shared secret derivation, and AES-GCM calldata encryption

Detailed documentation of the encryption flow used by SeismicSignedProvider to protect calldata and decrypt responses.

Overview

Seismic uses end-to-end encryption between the client and the node's Trusted Execution Environment (TEE). The encryption ensures that:

1. Calldata confidentiality -- Transaction input data is encrypted before leaving the client

2. Context binding -- Ciphertext is cryptographically bound to the transaction context (sender, nonce, chain ID) via Additional Authenticated Data (AAD)

3. Response privacy -- seismic_call responses are encrypted by the TEE and only the requesting client can decrypt them

The encryption scheme uses ECDH key agreement to derive a shared AES-GCM key, which is then used for symmetric encryption of calldata and decryption of responses.

Encryption Flow

Client                                          Seismic Node (TEE)
------                                          ------------------

1. Generate ephemeral secp256k1 keypair
   (ephemeral_sk, ephemeral_pk)

2. Fetch TEE public key  ----RPC----->
   seismic_getTeePublicKey()
                          <----RPC-----  tee_pubkey

3. ECDH(ephemeral_sk, tee_pubkey)
   = shared_point

4. Derive AES key from shared_point
   aes_key = KDF(shared_point)

5. For each transaction:
   a. Build AAD from tx context
      (sender, chain_id, nonce, to, value, seismic_elements)
   b. Generate encryption nonce (12 bytes)
   c. AES-GCM-encrypt(calldata, aes_key, nonce, AAD)
   d. Send encrypted tx  ----RPC----->
                                              e. Derive same shared_point
                                                 ECDH(tee_sk, ephemeral_pk)
                                              f. Derive same AES key
                                              g. Rebuild AAD from tx
                                              h. AES-GCM-decrypt(ciphertext)
                                              i. Execute with plaintext calldata

6. For seismic_call responses:
                          <----RPC-----  encrypted_response
   a. AES-GCM-decrypt(response, aes_key, nonce, AAD)
   b. Return plaintext result

Key Generation

Ephemeral Keypair

At provider creation, SeismicSignedProvider generates a fresh secp256k1 keypair:

ephemeral_sk  : 32-byte secp256k1 private key (random)
ephemeral_pk  : 33-byte compressed secp256k1 public key (derived from ephemeral_sk)

This keypair is:

• Generated once per provider instance

• Used for all ECDH key agreements with the TEE

• Not related to the wallet's signing key

• Ephemeral -- discarded when the provider is dropped

TEE Public Key

The node's TEE public key is fetched via the seismic_getTeePublicKey RPC method:

let tee_pubkey = provider.get_tee_pubkey().await?;

For SeismicSignedProvider:

• Fetched automatically during new() construction

• Cached for the lifetime of the provider

• Can be pre-fetched and passed to new_with_tee_pubkey() to avoid the async RPC call

For SeismicUnsignedProvider:

• Not fetched or cached automatically

• Available via get_tee_pubkey() for manual use

ECDH Shared Secret

The shared secret is derived using Elliptic Curve Diffie-Hellman (ECDH) on the secp256k1 curve:

shared_point = ECDH(ephemeral_sk, tee_pubkey)
             = ephemeral_sk * tee_pubkey

The TEE performs the same computation with its own private key:

shared_point = ECDH(tee_sk, ephemeral_pk)
             = tee_sk * ephemeral_pk

Both sides arrive at the same shared point due to the commutativity of ECDH:

ephemeral_sk * tee_pubkey = tee_sk * ephemeral_pk

AES-GCM Encryption

Key Derivation

The AES-256 key is derived from the ECDH shared point using a Key Derivation Function (KDF):

aes_key = KDF(shared_point)  // 32 bytes for AES-256

Encryption Parameters

Parameter	Size	Description
aes_key	32 bytes	AES-256 key derived from ECDH shared secret
nonce	12 bytes	AES-GCM nonce (unique per encryption)
plaintext	Variable	Transaction calldata to encrypt
aad	Variable	Additional Authenticated Data (transaction context)

Encryption Operation

ciphertext || auth_tag = AES-GCM-Encrypt(aes_key, nonce, plaintext, aad)

The output is the concatenation of:

• Ciphertext -- same length as the plaintext

• Authentication tag -- 16 bytes (AES-GCM standard)

Decryption Operation

plaintext = AES-GCM-Decrypt(aes_key, nonce, ciphertext || auth_tag, aad)

Decryption fails (raises an error) if:

• The AES key is incorrect

• The nonce does not match

• The AAD does not match (transaction context was altered)

• The ciphertext or authentication tag was tampered with

Additional Authenticated Data (AAD)

The AAD cryptographically binds the ciphertext to the transaction context. This prevents:

• Replay attacks -- Ciphertext cannot be reused in a different transaction

• Context manipulation -- Changing any transaction field invalidates the ciphertext

• Cross-chain attacks -- Ciphertext is bound to a specific chain ID

AAD Composition

The AAD is constructed from the following transaction fields, RLP-encoded:

Field	Type	Description
sender	Address	Transaction sender address
chain_id	u64	Chain ID of the target network
nonce	u64	Transaction nonce
to	Address	Transaction recipient address
value	U256	Transaction value in wei
seismic_elements	RLP-encoded	Seismic-specific transaction fields (encryption nonce, block hash, expiry, etc.)

If any AAD field changes between encryption and decryption, the authentication tag verification will fail and decryption will return an error. This is a security feature -- it ensures the ciphertext can only be used in the exact transaction context it was encrypted for.

AAD Construction

The AAD fields are RLP-encoded into a single byte sequence:

aad = RLP(sender, chain_id, nonce, to, value, seismic_elements)

The seismic_elements field itself contains:

• Encryption nonce (12 bytes)

• Client's ephemeral public key

• Recent block hash

• Expiry block number

Response Decryption

For seismic_call() requests, the TEE encrypts the response using the same shared secret:

1. The TEE computes ECDH(tee_sk, ephemeral_pk) to get the shared point

2. Derives the same AES key

3. Encrypts the call response with AES-GCM

4. Returns the encrypted response to the client

The SeismicSignedProvider decrypts the response:

// Internally, seismic_call() does:
// 1. Fill transaction fields (filler pipeline)
// 2. Encrypt calldata with AES-GCM
// 3. Send encrypted call to node
// 4. Receive encrypted response
// 5. Decrypt response with the same AES key
let result = provider.seismic_call(tx.into()).await?;

SeismicUnsignedProvider cannot decrypt responses because it does not have an ephemeral keypair. Use SeismicSignedProvider for any operation that requires reading encrypted responses.

Provider Comparison

Encryption Capability	SeismicSignedProvider	SeismicUnsignedProvider
Ephemeral keypair generation	Yes (at construction)	No
TEE pubkey fetching	Yes (cached at construction)	Yes (on-demand, not cached)
ECDH shared secret	Yes	No
Calldata encryption	Yes (automatic via fillers)	No
Response decryption	Yes (in seismic_call)	No

Security Properties

Forward Secrecy

Each SeismicSignedProvider instance generates a fresh ephemeral keypair. Compromising one provider's ephemeral key does not affect other providers or past sessions.

Nonce Uniqueness

AES-GCM requires unique nonces for each encryption under the same key. The Seismic filler pipeline generates fresh 12-byte nonces for each transaction, ensuring nonce uniqueness.

Reusing an AES-GCM nonce with the same key is catastrophic -- it allows an attacker to recover the plaintext. The SDK handles nonce generation automatically. Do not manually set encryption nonces unless you have a strong reason and understand the implications.

Authentication

The AES-GCM authentication tag ensures:

• The ciphertext has not been modified

• The AAD (transaction context) has not been modified

• The encryption key is correct

Any tampering with the ciphertext, AAD, or key results in a decryption failure.

Key Separation

The ephemeral keypair used for ECDH is separate from the wallet's signing key. Compromising the wallet key does not compromise past encrypted calldata (and vice versa).

Examples

Inspecting TEE Public Key

use seismic_prelude::foundry::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let url = "https://gcp-1.seismictest.net/rpc".parse()?;
    let provider = sreth_unsigned_provider(url);

    let tee_pubkey = provider.get_tee_pubkey().await?;
    println!("TEE public key: {tee_pubkey}");

    Ok(())
}

Signed Provider with Automatic Encryption

use seismic_prelude::foundry::*;
use alloy_signer_local::PrivateKeySigner;
use alloy_primitives::address;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let signer: PrivateKeySigner = "0xYOUR_PRIVATE_KEY".parse()?;
    let wallet = SeismicWallet::from(signer);
    let url = "https://gcp-1.seismictest.net/rpc".parse()?;

    // Provider automatically:
    // 1. Generates ephemeral keypair
    // 2. Fetches and caches TEE pubkey
    // 3. Derives ECDH shared secret
    let provider = sreth_signed_provider(wallet, url).await?;

    // Transaction calldata is automatically encrypted by the filler pipeline
    let tx = TransactionRequest::default()
        .to(address!("0x1234567890abcdef1234567890abcdef12345678"))
        .input(bytes!("0x60fe47b10000000000000000000000000000000000000000000000000000000000000042").into());

    // send_transaction: fillers populate fields, encrypt calldata, sign, send
    let pending = provider.send_transaction(tx).await?;
    let tx_hash = pending.watch().await?;

    // seismic_call: encrypt calldata, send, decrypt response
    let read_tx = TransactionRequest::default()
        .to(address!("0x1234567890abcdef1234567890abcdef12345678"))
        .input(bytes!("0x3fb5c1cb").into());

    let result = provider.seismic_call(read_tx.into()).await?;
    println!("Decrypted result: {result}");

    Ok(())
}

Notes

• Encryption is handled automatically by the filler pipeline -- you do not need to encrypt calldata manually

• The ephemeral keypair is generated per provider instance, not per transaction

• The TEE public key is assumed to be static for the lifetime of a provider instance

• All encryption uses AES-256-GCM (256-bit key, 96-bit nonce, 128-bit authentication tag)

• The ECDH key agreement uses the secp256k1 curve (same curve as Ethereum signatures)

• The seismic-enclave crate (v0.1.0) provides the underlying cryptographic operations

See Also

• SeismicSignedProvider -- Provider with full encryption capabilities

• SeismicUnsignedProvider -- Provider without encryption

• Provider Overview -- Comparison of provider types and filler pipelines

• Installation -- Add seismic-alloy to your project