# Rust — seismic-alloy

Rust SDK for [Seismic](https://seismic.systems), built on [Alloy](https://github.com/alloy-rs/alloy) (v1.1.0). Requires **Rust 1.82+**.

```toml
[dependencies]
seismic-alloy = { git = "https://github.com/SeismicSystems/seismic-alloy" }
```

## Quick Example

```rust
use seismic_prelude::foundry::*;
use alloy_signer_local::PrivateKeySigner;

#[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()?;

    let provider = SeismicSignedProvider::<SeismicReth>::new(wallet, url).await?;

    // All standard Alloy provider methods work
    let block_number = provider.get_block_number().await?;
    println!("Block number: {block_number}");

    Ok(())
}
```

```rust
// Unsigned provider -- read-only (no private key needed)
use seismic_prelude::foundry::*;

let url = "https://gcp-1.seismictest.net/rpc".parse()?;
let provider = sreth_unsigned_provider(url);

let block = provider.get_block_number().await?;
```

## Documentation Navigation

### Getting Started

| Section                                                                     | Description                                      |
| --------------------------------------------------------------------------- | ------------------------------------------------ |
| [**Installation**](https://docs.seismic.systems/clients/alloy/installation) | Cargo setup, git dependencies, and feature flags |
| [**Provider**](https://docs.seismic.systems/clients/alloy/provider)         | Signed and unsigned provider types               |

### Provider Reference

| Section                                                                                                      | Description                                                             |
| ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- |
| [**SeismicSignedProvider**](https://docs.seismic.systems/clients/alloy/provider/seismic-signed-provider)     | Full-featured provider with wallet, encryption, and response decryption |
| [**SeismicUnsignedProvider**](https://docs.seismic.systems/clients/alloy/provider/seismic-unsigned-provider) | Read-only provider for public operations                                |
| [**Encryption**](https://docs.seismic.systems/clients/alloy/provider/encryption)                             | TEE key exchange, ECDH, AES-GCM calldata encryption                     |

## Quick Links

### By Task

* **Create a signed provider** -> [SeismicSignedProvider](https://docs.seismic.systems/clients/alloy/provider/seismic-signed-provider)
* **Create a read-only provider** -> [SeismicUnsignedProvider](https://docs.seismic.systems/clients/alloy/provider/seismic-unsigned-provider)
* **Understand calldata encryption** -> [Encryption](https://docs.seismic.systems/clients/alloy/provider/encryption)
* **Install the crate** -> [Installation](https://docs.seismic.systems/clients/alloy/installation)

### By Component

* **Provider types** -> [SeismicSignedProvider](https://docs.seismic.systems/clients/alloy/provider/seismic-signed-provider), [SeismicUnsignedProvider](https://docs.seismic.systems/clients/alloy/provider/seismic-unsigned-provider)
* **Encryption** -> [Encryption](https://docs.seismic.systems/clients/alloy/provider/encryption)
* **Convenience constructors** -> `sreth_signed_provider()`, `sfoundry_signed_provider()`

## Features

* **Shielded Transactions** -- Encrypt calldata with TEE public key via AES-GCM
* **Signed Reads** -- Prove identity in `eth_call` with `seismic_call()`
* **Two Provider Types** -- `SeismicSignedProvider` (full capabilities) and `SeismicUnsignedProvider` (read-only)
* **Automatic Encryption Pipeline** -- Filler chain handles encryption transparently
* **Type 0x4A Transactions** -- Native support for Seismic transaction type
* **Full Alloy Compatibility** -- All standard Alloy `Provider` methods work unchanged

## Architecture

The SDK extends Alloy's provider model with a filler pipeline that automatically handles Seismic-specific transaction fields and encryption:

```
seismic-alloy (workspace)
├── consensus    -- Seismic transaction types and consensus logic
├── network      -- SeismicNetwork trait, SeismicReth, SeismicFoundry
├── provider     -- SeismicSignedProvider, SeismicUnsignedProvider, fillers
├── rpc-types    -- Seismic-specific RPC request/response types
├── genesis      -- Genesis configuration types
└── prelude      -- Convenience re-exports from all crates

SeismicSignedProvider filler chain:
  WalletFiller
  -> NonceFiller + ChainIdFiller
  -> SeismicElementsFiller
  -> SeismicGasFiller
  -> (encrypt calldata)
  -> send transaction
  -> (decrypt response)
```

## Network Types

The SDK defines two network configurations:

| Network          | Type        | Description                                |
| ---------------- | ----------- | ------------------------------------------ |
| `SeismicReth`    | Production  | Seismic devnet/testnet/mainnet             |
| `SeismicFoundry` | Development | Local Seismic Foundry (sfoundry) instances |

Both implement the `SeismicNetwork` trait and can be used as the generic parameter `N` in provider types.

### Guides & Examples

| Section                                                                                                    | Description                                             |
| ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| [**Guides**](https://docs.seismic.systems/clients/alloy/guides)                                            | Step-by-step tutorials for shielded writes and reads    |
| [**Shielded Write Guide**](https://docs.seismic.systems/clients/alloy/guides/shielded-write)               | Encrypted transaction lifecycle and security parameters |
| [**Signed Reads Guide**](https://docs.seismic.systems/clients/alloy/guides/signed-reads)                   | Encrypted eth\_call with identity proof                 |
| [**Examples**](https://docs.seismic.systems/clients/alloy/examples)                                        | Complete, runnable code examples                        |
| [**Basic Setup**](https://docs.seismic.systems/clients/alloy/examples/basic-setup)                         | Provider creation and connection verification           |
| [**Shielded Write Complete**](https://docs.seismic.systems/clients/alloy/examples/shielded-write-complete) | Full lifecycle: deploy, write, read, inspect receipt    |
| [**Signed Read Pattern**](https://docs.seismic.systems/clients/alloy/examples/signed-read-pattern)         | Comparing encrypted and transparent reads               |
| [**Contract Deployment**](https://docs.seismic.systems/clients/alloy/examples/contract-deployment)         | Deploy, verify, interact, and subscribe to events       |

## Next Steps

1. [**Install seismic-alloy**](https://docs.seismic.systems/clients/alloy/installation) -- Add the crate to your project
2. [**Create a signed provider**](https://docs.seismic.systems/clients/alloy/provider/seismic-signed-provider) -- Connect with full capabilities
3. [**Understand encryption**](https://docs.seismic.systems/clients/alloy/provider/encryption) -- Learn how calldata encryption works
4. [**Explore unsigned providers**](https://docs.seismic.systems/clients/alloy/provider/seismic-unsigned-provider) -- Read-only access
5. [**Follow a guide**](https://docs.seismic.systems/clients/alloy/guides) -- Step-by-step shielded write or signed read tutorial
6. [**Run an example**](https://docs.seismic.systems/clients/alloy/examples) -- Complete, runnable code examples