> 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/architecture.md).

# SDK architecture

How the SDK packages, the white-label app and a typical integration are put 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 %}

This page shows three views: the packages, the white-label app built on them, and the call sequence of a typical integration.

## Packages

```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 (BTFS storage)"]
  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.*

`ethereum` depends on `encryption`, `storage` and `utils`. `storage` and `encryption` depend on `types` and `utils`. The `encryptor` package talks to the browser extension and implements the `EncryptorExtension` interface that `ethereum`'s `Encryptor` client expects, so you pass it in at runtime.

## The white-label app

```mermaid
flowchart LR
  pages["Nuxt pages and components<br/>mail, chat, settings, dashboard"]
  comp["Composables<br/>useMailClient, useChatClient, useEncryptor, usePollinationX, useWallet"]
  sdk["SDK clients<br/>Mail, Chat, Encryptor, User"]
  wc["Wallet connectors<br/>MetaMask, Coinbase Wallet, WalletConnect"]
  nets["Supported networks (12)"]
  ee["Encryptor extension"]
  px["PollinationX storage"]
  pages --> comp
  comp --> sdk
  comp --> wc
  wc --> nets
  sdk --> nets
  sdk --> ee
  sdk --> px
```

*Figure: How the white-label app is layered, from Nuxt pages down to the SDK, the wallet and the services it talks to.*

The app creates its clients when the connected account or network changes. It builds a `WalletClient` from the connected wallet, a `PollinationX` storage provider, an `EncryptionHandler` that holds `EncryptorAesEncryption`, and then `Mail`, `Chat`, `Encryptor` and `User` clients. If the active network has no contracts configured for a client, that client is not created. See [Run locally](https://wiki.4thtech.io/products/white-label/run-locally.md).

## An integration

```mermaid
sequenceDiagram
  participant App as Your app
  participant W as WalletClient
  participant S as Storage provider
  participant M as Mail client
  participant N as Network
  App->>W: create a wallet client for the chosen network
  App->>S: create the storage provider
  App->>M: new Mail(walletClient, remoteStorageProvider, appId, encryptionHandler)
  App->>M: onNew(null, receiver, callback)
  App->>M: send(envelope, encryption)
  M->>S: store encrypted attachments and envelope
  M->>W: sendTransaction (link, checksum)
  W->>N: user signs and submits
  N-->>M: new-mail event
  M-->>App: callback(receivedEnvelope)
```

*Figure: The call sequence of the quickstart: build the clients, listen for new mail, then send one encrypted mail.*

Follow the code in the [SDK quickstart](https://wiki.4thtech.io/developers/sdk/quickstart.md).

## Design notes

* **No keys in the SDK.** Your wallet client signs. The SDK only encodes calls.
* **Storage is pluggable.** Implement `RemoteStorageProvider` to use your own storage.
* **Encryption is pluggable.** Implement the `Encryption` interface and add it to the handler.
* **Chains carry their contracts.** Each chain exported from `@4thtech-sdk/ethereum` includes the contract addresses the clients need. Addresses are listed on the [Deployments page](https://wiki.4thtech.io/deployments/deployments-1.md).
