# seismic-viem

Low-level TypeScript SDK for [Seismic](https://seismic.systems), built on [viem](https://viem.sh/) 2.x. Provides shielded public and wallet clients, encrypted contract interactions, signed reads, chain configs, and precompile access. This is the foundation that [seismic-react](https://docs.seismic.systems/clients/typescript/react) builds upon.

```bash
npm install seismic-viem viem
```

## Quick Example

```typescript
import { http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { createShieldedWalletClient, seismicTestnet } from "seismic-viem";

const client = await createShieldedWalletClient({
  chain: seismicTestnet,
  transport: http(),
  account: privateKeyToAccount("0x..."),
});

// Smart write — auto-detects shielded params, encrypts only when needed
const hash = await client.writeContract({
  address: "0x...",
  abi: myContractAbi,
  functionName: "transfer", // has suint256/saddress params → encrypted automatically
  args: ["0x...", 100n],
});

// Smart read — auto-detects shielded params, uses signed read only when needed
const balance = await client.readContract({
  address: "0x...",
  abi: myContractAbi,
  functionName: "balanceOf", // has saddress param → signed read automatically
  args: ["0x..."],
});
```

## Architecture

```
seismic-viem
├── Client Layer
│   ├── createShieldedPublicClient  — read-only, TEE key, precompiles
│   └── createShieldedWalletClient  — full capabilities, encryption pipeline
├── Contract Layer
│   ├── getShieldedContract          — .read / .write (smart) / .sread / .swrite (force shielded) / .tread / .twrite (force transparent) / .dwrite
│   ├── shieldedWriteContract        — standalone encrypted write
│   └── signedReadContract           — standalone signed read
├── Chain Configs
│   ├── seismicTestnet               — public testnet (chain ID 5124)
│   ├── sanvil                       — local dev (chain ID 31337)
│   └── createSeismicDevnet          — custom chain factory
├── Encryption
│   ├── getEncryption                — ECDH key exchange → AES key
│   └── AesGcmCrypto                 — encrypt/decrypt calldata
└── Precompiles
    ├── rng                          — random number generation
    ├── ecdh                         — key exchange
    ├── aesGcmEncrypt / Decrypt      — on-chain encryption
    ├── hkdf                         — key derivation
    └── secp256k1Sig                 — signature generation
```

## Documentation Navigation

### Getting Started

| Section                                                                               | Description                                           |
| ------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| [**Installation**](https://docs.seismic.systems/clients/typescript/viem/installation) | Install seismic-viem, configure viem peer dependency  |
| [**Chains**](https://docs.seismic.systems/clients/typescript/viem/chains)             | Pre-configured chain definitions for Seismic networks |

### Client Reference

| Section                    | Description                                                           |
| -------------------------- | --------------------------------------------------------------------- |
| **Shielded Public Client** | Read-only client with TEE key exchange and precompile access          |
| **Shielded Wallet Client** | Full-featured client with encryption pipeline and transaction signing |

### Contract Interaction

| Section               | Description                                                                                                                                   |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **Contract Instance** | `getShieldedContract` for `.read`, `.write` (smart), `.sread`, `.swrite` (force shielded), `.tread`, `.twrite` (force transparent), `.dwrite` |
| **Shielded Writes**   | Encrypt calldata and send Seismic transactions (type 0x4A)                                                                                    |
| **Signed Reads**      | Prove caller identity in `eth_call` via `seismic_call`                                                                                        |

### Infrastructure

| Section                                                                   | Description                                                     |
| ------------------------------------------------------------------------- | --------------------------------------------------------------- |
| [**Chains**](https://docs.seismic.systems/clients/typescript/viem/chains) | `seismicTestnet`, `sanvil`, `createSeismicDevnet` chain configs |
| **Encryption**                                                            | ECDH key exchange, AES-GCM calldata encryption                  |
| **Precompiles**                                                           | RNG, ECDH, AES-GCM, HKDF, secp256k1 signing precompile bindings |

## Features

* **Shielded Transactions** -- Encrypt calldata with TEE public key via AES-GCM before sending
* **Signed Reads** -- Prove identity in `eth_call` with signed read requests
* **Two Client Types** -- `createShieldedPublicClient` (read-only) and `createShieldedWalletClient` (full capabilities)
* **Smart Routing** -- `.read` and `.write` auto-detect shielded parameters and route to the correct path
* **Contract Abstraction** -- `getShieldedContract` provides `.read`, `.write` (smart), `.sread`, `.swrite` (force shielded), `.tread`, `.twrite` (force transparent), and `.dwrite` methods
* **Automatic Encryption Pipeline** -- Calldata encryption handled transparently in the client layer
* **Type 0x4A Transactions** -- Native support for Seismic transaction type with custom chain formatters
* **Precompile Bindings** -- TypeScript wrappers for all Seismic precompiles (RNG, ECDH, AES-GCM, HKDF, secp256k1)
* **Chain Configs** -- Pre-configured chain definitions for testnet, local dev, and custom devnets
* **Full viem Compatibility** -- All standard viem client methods work unchanged

## Quick Links

### By Task

* **Create a wallet client** -> Shielded Wallet Client
* **Create a read-only client** -> Shielded Public Client
* **Interact with a contract** -> Contract Instance
* **Send an encrypted transaction** -> Shielded Writes
* **Read with identity proof** -> Signed Reads
* **Connect to a network** -> [Chains](https://docs.seismic.systems/clients/typescript/viem/chains)
* **Understand calldata encryption** -> Encryption
* **Install the package** -> [Installation](https://docs.seismic.systems/clients/typescript/viem/installation)

### By Component

* **Client types** -> Shielded Public Client, Shielded Wallet Client
* **Contract interaction** -> Contract Instance, Shielded Writes, Signed Reads
* **Chains** -> [Chains](https://docs.seismic.systems/clients/typescript/viem/chains) (`seismicTestnet`, `sanvil`, `createSeismicDevnet`)
* **Encryption** -> Encryption (`getEncryption`, `AesGcmCrypto`)
* **Precompiles** -> Precompiles (`rng`, `ecdh`, `aesGcmEncrypt`, `hkdf`, `secp256k1Sig`)

## Comparison with seismic-react

| Aspect               | seismic-viem                          | seismic-react                           |
| -------------------- | ------------------------------------- | --------------------------------------- |
| **Level**            | Low-level SDK                         | React hooks layer                       |
| **Framework**        | Framework-agnostic TypeScript         | React 18+                               |
| **Foundation**       | Built directly on viem 2.x            | Built on seismic-viem + wagmi           |
| **Client creation**  | Manual (`createShieldedWalletClient`) | Automatic via `ShieldedWalletProvider`  |
| **State management** | Manual                                | React hooks (`useShieldedWallet`, etc.) |
| **Use when**         | Server-side, scripts, non-React apps  | React applications                      |

{% hint style="info" %}
If you are building a React application, consider using [seismic-react](https://docs.seismic.systems/clients/typescript/react) which provides React hooks on top of seismic-viem. For Node.js scripts, server-side code, or non-React frontends, use seismic-viem directly.
{% endhint %}

## Next Steps

1. [**Install seismic-viem**](https://docs.seismic.systems/clients/typescript/viem/installation) -- Add the package to your project
2. [**Configure a chain**](https://docs.seismic.systems/clients/typescript/viem/chains) -- Connect to testnet or local dev
3. **Create a shielded wallet client** -- Connect with full capabilities
4. **Understand encryption** -- Learn how calldata encryption works
5. **Interact with contracts** -- Use `getShieldedContract` for reads and writes
6. **Explore precompiles** -- Access on-chain RNG, ECDH, and AES-GCM