# Python — seismic-web3

Python SDK for [Seismic](https://seismic.systems), built on [web3.py](https://github.com/ethereum/web3.py). Requires **Python 3.10+**.

```bash
pip install seismic-web3
```

Or with [uv](https://docs.astral.sh/uv/):

```bash
uv add seismic-web3
```

## Quick Example

```python
import os
from seismic_web3 import SEISMIC_TESTNET, PrivateKey

pk = PrivateKey.from_hex_str(os.environ["PRIVATE_KEY"])

# Wallet client — full capabilities (requires private key)
w3 = SEISMIC_TESTNET.wallet_client(pk)

contract = w3.seismic.contract(address="0x...", abi=ABI)

# Shielded write — calldata is encrypted
tx_hash = contract.write.setNumber(42)
receipt = w3.eth.wait_for_transaction_receipt(tx_hash)

# Signed read — encrypted eth_call, proves your identity
result = contract.read.getNumber()
```

```python
# Public client — read-only (no private key needed)
public = SEISMIC_TESTNET.public_client()

contract = public.seismic.contract(address="0x...", abi=ABI)
result = contract.tread.getNumber()
```

## Documentation Navigation

### Getting Started

| Section                                                              | Description                                    |
| -------------------------------------------------------------------- | ---------------------------------------------- |
| [**Client**](https://docs.seismic.systems/clients/python/client)     | Create sync/async wallet and public clients    |
| [**Chains**](https://docs.seismic.systems/clients/python/chains)     | Chain configuration (SEISMIC\_TESTNET, SANVIL) |
| [**Contract**](https://docs.seismic.systems/clients/python/contract) | Interact with shielded and public contracts    |

### Guides

| Section                                                          | Description                                  |
| ---------------------------------------------------------------- | -------------------------------------------- |
| [**Guides**](https://docs.seismic.systems/clients/python/guides) | Step-by-step tutorials and runnable examples |

### API Reference

| Section                                                                                                                                            | Description                                            |
| -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| [**API Reference**](https://docs.seismic.systems/clients/python/api-reference)                                                                     | Complete API documentation for all types and functions |
| [**Types**](https://github.com/SeismicSystems/seismic/blob/main/docs/gitbook/clients/python/api-reference/types/README.md)                         | Primitive types (Bytes32, PrivateKey, etc.)            |
| [**Transaction Types**](https://github.com/SeismicSystems/seismic/blob/main/docs/gitbook/clients/python/api-reference/transaction-types/README.md) | Seismic transaction dataclasses                        |
| [**EIP-712**](https://github.com/SeismicSystems/seismic/blob/main/docs/gitbook/clients/python/api-reference/eip712/README.md)                      | EIP-712 typed data signing functions                   |

### Advanced Features

| Section                                                                    | Description                                |
| -------------------------------------------------------------------------- | ------------------------------------------ |
| [**Namespaces**](https://docs.seismic.systems/clients/python/namespaces)   | w3.seismic namespace methods               |
| [**Precompiles**](https://docs.seismic.systems/clients/python/precompiles) | Privacy-preserving cryptographic functions |
| [**SRC20**](https://docs.seismic.systems/clients/python/src20)             | SRC20 token standard support               |
| [**ABIs**](https://docs.seismic.systems/clients/python/abis)               | Built-in contract ABIs and helpers         |

## Quick Links

### By Task

* **Send a shielded transaction** → [Shielded Write Guide](https://docs.seismic.systems/clients/python/guides/shielded-write)
* **Execute a signed read** → [Signed Reads Guide](https://docs.seismic.systems/clients/python/guides/signed-reads)
* **Work with SRC20 tokens** → [SRC20 Documentation](https://docs.seismic.systems/clients/python/src20)
* **Use async client** → [Client Documentation](https://docs.seismic.systems/clients/python/client/create-async-wallet-client)
* **Configure custom chain** → [Chains Documentation](https://docs.seismic.systems/clients/python/chains/chain-config)

### By Component

* **Client factories** → [create\_wallet\_client](https://docs.seismic.systems/clients/python/client/create-wallet-client), [create\_public\_client](https://docs.seismic.systems/clients/python/client/create-public-client)
* **Contract wrappers** → [ShieldedContract](https://docs.seismic.systems/clients/python/contract/shielded-contract), [PublicContract](https://docs.seismic.systems/clients/python/contract/public-contract)
* **Encryption** → [EncryptionState](https://docs.seismic.systems/clients/python/client/encryption-state), [Precompiles](https://docs.seismic.systems/clients/python/precompiles)
* **Transaction types** → [UnsignedSeismicTx](https://docs.seismic.systems/clients/python/api-reference/transaction-types/unsigned-seismic-tx), [SeismicElements](https://docs.seismic.systems/clients/python/api-reference/transaction-types/seismic-elements)

## Features

* **🔒 Shielded Transactions** - Encrypt calldata with TEE public key
* **📝 Signed Reads** - Prove identity in eth\_call
* **🪙 SRC20 Support** - Built-in support for private tokens
* **⚡ Async/Await** - Full async support with AsyncWeb3
* **🔑 EIP-712** - Structured typed data signing
* **🛠️ Precompiles** - Access Mercury EVM cryptographic precompiles
* **🌐 Web3.py Compatible** - Standard Web3 instance with Seismic extensions

## Architecture

The SDK extends `web3.py` with a custom `w3.seismic` namespace:

```
Web3 (standard web3.py)
├── eth (standard)
├── net (standard)
└── seismic (Seismic-specific) ✨
    ├── send_shielded_transaction()
    ├── signed_call()
    ├── get_tee_public_key()
    ├── deposit()
    └── contract() → ShieldedContract
                     ├── .write (shielded)
                     ├── .read (signed)
                     ├── .twrite (transparent)
                     ├── .tread (transparent)
                     └── .dwrite (debug)
```

## Next Steps

1. [**Install and setup a client**](https://docs.seismic.systems/clients/python/client) - Get connected to Seismic
2. [**Send your first shielded transaction**](https://docs.seismic.systems/clients/python/guides/shielded-write) - Step-by-step guide
3. [**Explore the API reference**](https://docs.seismic.systems/clients/python/api-reference) - Deep dive into all types and functions