> For the complete documentation index, see [llms.txt](https://wiki.4thtech.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.4thtech.io/developers/sdk/how-it-fits.md).

# How the SDK fits together

How the SDK clients, envelopes, app IDs, encryption handler, storage providers and the Encryptor connector fit together.

{% hint style="info" %}
**Status: Production-ready, stable.** The 4thTech SDK and the BlockMail & BlockChat white-label apps are supported; no new features are planned. Last release: SDK 0.5.13 (25 Nov 2025).
{% endhint %}

You build with five ideas: a wallet client, a storage provider, an encryption handler, an app ID and a client class (`Mail` or `Chat`). This page explains each one and how they connect.

```mermaid
flowchart TD
  types["@4thtech-sdk/types"]
  utils["@4thtech-sdk/utils"]
  enc["@4thtech-sdk/encryption"]
  sto["@4thtech-sdk/storage"]
  ext["@4thtech-sdk/encryptor"]
  eth["@4thtech-sdk/ethereum<br/>Mail, Chat, Encryptor, User"]
  viem["viem"]
  px["PollinationX (partner storage network, BTFS)"]
  ee["Encryptor browser extension"]
  utils --> types
  enc --> types
  enc --> utils
  sto --> enc
  sto --> utils
  eth --> enc
  eth --> sto
  eth --> utils
  eth --> viem
  sto -. "PollinationX provider" .-> px
  ext -. "talks to" .-> ee
  ext -. "implements EncryptorExtension" .-> eth
```

*Figure: The 4thTech SDK packages and what they depend on. Solid arrows are package imports; dotted lines are runtime connections.*

## The pieces

**Wallet client.** The SDK does not hold keys or sign for you. You pass in an object that implements the `WalletClient` interface from `@4thtech-sdk/types`: a `chain`, a `getAddress()` method and a `sendTransaction()` method. The user's own wallet signs every transaction. See [Types](https://wiki.4thtech.io/developers/sdk/types.md).

**Clients.** `Mail` and `Chat` in `@4thtech-sdk/ethereum` encode contract calls, hand them to your wallet client and read events back. `Encryptor` and `User` handle each user's public encryption key on-chain. See [Mail](https://wiki.4thtech.io/developers/sdk/ethereum/mail.md), [Chat](https://wiki.4thtech.io/developers/sdk/ethereum/chat.md) and [Encryptor](https://wiki.4thtech.io/developers/sdk/ethereum/encryptor.md).

**Envelope.** A mail is an envelope: `content` (subject, optional body, optional attachments) and the `receiver` address. A received envelope also carries the `sender`, `sentAt`, `openedAt`, the mail `index` and storage metadata (URL and checksum). Mail contents are stored off-chain; the chain records the link and a checksum.

**Storage provider.** Mail attachments and envelopes go to a `RemoteStorageProvider`, such as [PollinationX](https://wiki.4thtech.io/developers/sdk/storage/pollination-x.md). Chat messages are stored on-chain directly. See [Storage](https://wiki.4thtech.io/developers/sdk/storage.md).

**Encryption handler.** An `EncryptionHandler` holds the encryption implementations your app supports and decrypts what it receives. `AesEncryption` uses a secret key you manage. `EncryptorAesEncryption` derives a shared secret from the two users' public keys with the Encryptor extension. See [Encryption](https://wiki.4thtech.io/developers/sdk/encryption.md).

**Encryptor connector.** `EncryptorExtensionConnector` in `@4thtech-sdk/encryptor` is the bridge to the [Encryptor](https://wiki.4thtech.io/products/encryptor.md) browser extension. See [Encryptor package](https://wiki.4thtech.io/developers/sdk/encryptor.md).

**App ID.** A 32-byte identifier for your app. Mail and chat are stored per app ID. If you leave it out, the SDK uses the zero ID, and every app that also uses it shares the same mail. Apps that share an ID must support the same encryption and storage, or they cannot read each other's mail.

## Fees

Mail and chat sends can carry a fee that depends on the app ID. The clients read and attach it for you; see [Fee collector](https://wiki.4thtech.io/developers/sdk/ethereum/fee-collector.md).

## Where to go next

* Build it: [SDK quickstart](https://wiki.4thtech.io/developers/sdk/quickstart.md)
* See the layers: [SDK architecture](https://wiki.4thtech.io/developers/sdk/architecture.md)
