Skip to content

Update dbEncryptionKey setup #445

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Nov 23, 2025
Merged

Update dbEncryptionKey setup #445

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
55ec28e
Update dbEncryptionKey setup
humanagent Oct 18, 2025
3435b38
Update encryption key example
humanagent Oct 18, 2025
a6fa6d7
Update keys in agent creation
humanagent Oct 18, 2025
2439fc0
Update doc headings size
humanagent Oct 18, 2025
85db5df
Update encryption key format
humanagent Nov 23, 2025
f05c541
Refactor encryption key setup
humanagent Nov 23, 2025
316811e
Merge branch 'main' into humanagent/feature-20251018-122308
humanagent Nov 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 18 additions & 21 deletions docs/pages/agents/build-agents/create-a-client.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,15 +7,18 @@ Create an XMTP agent that can use the signing capabilities provided by a signer.
```tsx [Node]
import { Agent } from '@xmtp/agent-sdk';
import { createSigner, createUser } from '@xmtp/agent-sdk/user';
import { getRandomValues } from 'node:crypto';

// Replace with your own wallet key and encryption key
const walletKey = "0xprivateKey";
const db_encryptionKey = "0xencryptionKey";

// Option 1: Create a local user + signer
const user = createUser('0xprivateKey');
const signer = createSigner(user);
const user = createUser(walletKey);
const dbEncryptionKey = Buffer.from(db_encryptionKey).toString("hex")

const agent = await Agent.create(signer, {
env: 'dev', // or 'production'
dbEncryptionKey: `0x${getRandomValues(new Uint8Array(32))}`, // save it for later
dbEncryptionKey, // save it for later
});
```

Expand All @@ -25,36 +28,36 @@ The XMTP Agent SDK allows you to use environment variables (`process.env`) for e

**Available variables:**

| Variable | Purpose | Example |
| ------------------------ | ------------------------------------------------------------------------------------ | --------------------------------------- |
| `XMTP_WALLET_KEY` | Private key for wallet | `XMTP_WALLET_KEY=0x1234...abcd` |
| `XMTP_ENV` | XMTP network environment (`local`, `dev`, or `production`) | `XMTP_ENV=dev` or `XMTP_ENV=production` |
| `XMTP_DB_ENCRYPTION_KEY` | Database encryption key for the local database (32 bytes, hex string with 0x prefix) | `XMTP_DB_ENCRYPTION_KEY=0xabcd...1234` |
| Variable | Purpose | Example |
| ------------------------ | -------------------------------------------------------------- | --------------------------------------- |
| `XMTP_WALLET_KEY` | Private key for wallet | `XMTP_WALLET_KEY=0x1234...abcd` |
| `XMTP_ENV` | XMTP network environment (`local`, `dev`, or `production`) | `XMTP_ENV=dev` or `XMTP_ENV=production` |
| `XMTP_DB_ENCRYPTION_KEY` | Database encryption key for the local database (32 bytes, hex) | `XMTP_DB_ENCRYPTION_KEY=0xabcd...1234` |

Using the environment variables, you can setup your agent in just a few lines of code:

### Generate random keys
## Generate random keys

```tsx [Node]
import { generatePrivateKey } from 'viem';
import { getRandomValues } from 'node:crypto';

const walletKey = generatePrivateKey();
const encryptionKeyHex = `0x${getRandomValues(new Uint8Array(32))}`;
const encryptionKeyHex = getRandomValues(new Uint8Array(32));

console.log(`Wallet key: ${walletKey}`);
console.log(`Encryption key: ${encryptionKeyHex}`);
```

Use this [script to generate](https://github.com/xmtplabs/xmtp-agent-examples) random XMTP keys:
Use this [script to generate](https://github.com/ephemeraHQ/xmtp-agent-examples) random XMTP keys:

```bash
yarn gen:keys
```

> Running the command will append keys to your existing .env file.

### Use environment variables
## Use environment variables

```tsx [Node]
// Load variables from .env file
Expand All @@ -66,8 +69,6 @@ const agent = await Agent.createFromEnv();

## Configuration options

### Configure an XMTP client

You can configure an XMTP client with these options passed to `Agent.create`:

```tsx [Node]
Expand Down Expand Up @@ -121,13 +122,9 @@ apiUrl?: string;
*/
dbPath?: string | null | ((inboxId: string) => string);
/**
* Encryption key for the local DB (32 bytes)
*
* Accepts either:
* - Uint8Array (32 bytes)
* - Hex string with 0x prefix (64 hex characters representing 32 bytes)
* Encryption key for the local DB
*/
dbEncryptionKey?: Uint8Array | `0x${string}`;
dbEncryptionKey?: Uint8Array;
/**
* Allow configuring codecs for additional content types
*/
Expand Down
4 changes: 2 additions & 2 deletions docs/pages/agents/get-started/build-an-agent.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,8 +71,8 @@ XMTP creates local database files in the `dbPath` (default is `'/'`) directory.
To run an example XMTP agent, you must create a `.env` file with the following variables:

```bash
XMTP_WALLET_KEY= # the private key of the wallet
XMTP_DB_ENCRYPTION_KEY= # encryption key for the local database
XMTP_WALLET_KEY=0x # the private key of the wallet
XMTP_DB_ENCRYPTION_KEY=0x # encryption key for the local database
XMTP_ENV=dev # local, dev, production
```

Expand Down