Merge branch 'main' into humanagent/feature-20251024-200221

Author: jhaaaa

docs/pages/agents/build-agents/create-a-client.mdx

@@ -15,7 +15,7 @@ const signer = createSigner(user);
 
 const agent = await Agent.create(signer, {
   env: 'dev', // or 'production'
-  dbEncryptionKey: getRandomValues(new Uint8Array(32)), // save it for later
+  dbEncryptionKey: `0x${getRandomValues(new Uint8Array(32))}`, // save it for later
 });
 ```
 
@@ -25,11 +25,11 @@ 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) | `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 string with 0x prefix) | `XMTP_DB_ENCRYPTION_KEY=0xabcd...1234`  |
 
 Using the environment variables, you can setup your agent in just a few lines of code:
 
@@ -40,7 +40,7 @@ import { generatePrivateKey } from 'viem';
 import { getRandomValues } from 'node:crypto';
 
 const walletKey = generatePrivateKey();
-const encryptionKeyHex = getRandomValues(new Uint8Array(32));
+const encryptionKeyHex = `0x${getRandomValues(new Uint8Array(32))}`;
 
 console.log(`Wallet key: ${walletKey}`);
 console.log(`Encryption key: ${encryptionKeyHex}`);
@@ -121,9 +121,13 @@ apiUrl?: string;
  */
 dbPath?: string | null | ((inboxId: string) => string);
 /**
- * Encryption key for the local DB
+ * Encryption key for the local DB (32 bytes)
+ *
+ * Accepts either:
+ * - Uint8Array (32 bytes)
+ * - Hex string with 0x prefix (64 hex characters representing 32 bytes)
  */
-dbEncryptionKey?: Uint8Array;
+dbEncryptionKey?: Uint8Array | `0x${string}`;
 /**
  * Allow configuring codecs for additional content types
  */

docs/pages/agents/concepts/identity.mdx

@@ -36,7 +36,7 @@ When you call `Agent.create()`, the following steps happen under the hood:
 
 The `dbEncryptionKey` client option is used by the Node, React Native, Android, and Swift SDKs only.
 
-The encryption key is critical to the stability and continuity of an XMTP client. It encrypts the local SQLite database created when you call `Client.create()`, and must be provided every time you create or build a client.
+The encryption key is used together with an auto-generated salt to encrypt the local database using [SQLCipher](https://www.zetetic.net/sqlcipher/). It encrypts the database created when you call `Agent.create()`.
 
 This encryption key is not stored or persisted by the XMTP SDK, so it's your responsibility as the app developer to store it securely and consistently.
 

docs/pages/chat-apps/core-messaging/create-a-client.mdx

@@ -102,8 +102,12 @@ const signer: Signer = {
  *
  * This value must be consistent when creating a client with an existing
  * database.
+ *
+ * You can provide the key as either:
+ * - Uint8Array (32 bytes)
+ * - Hex string with 0x prefix (64 hex characters representing 32 bytes)
  */
-const dbEncryptionKey = getRandomValues(new Uint8Array(32));
+const dbEncryptionKey = `0x${getRandomValues(new Uint8Array(32))}`;
 
 const client = await Client.create(
   signer,
@@ -219,9 +223,13 @@ type ClientOptions = {
    */
   dbPath?: string | null | ((inboxId: string) => string);
   /**
-   * Encryption key for the local DB
+   * Encryption key for the local DB (32 bytes)
+   *
+   * Accepts either:
+   * - Uint8Array (32 bytes)
+   * - Hex string with 0x prefix (64 hex characters representing 32 bytes)
    */
-  dbEncryptionKey?: Uint8Array;
+  dbEncryptionKey?: Uint8Array | `0x${string}`;
   /**
    * Enable structured JSON logging
    */
@@ -307,9 +315,13 @@ type ClientOptions = {
    */
   dbPath?: string | null | ((inboxId: string) => string);
   /**
-   * Encryption key for the local DB
+   * Encryption key for the local DB (32 bytes)
+   *
+   * Accepts either:
+   * - Uint8Array (32 bytes)
+   * - Hex string with 0x prefix (64 hex characters representing 32 bytes)
    */
-  dbEncryptionKey?: Uint8Array;
+  dbEncryptionKey?: Uint8Array | `0x${string}`;
   /**
    * Allow configuring codecs for additional content types
    */

docs/pages/chat-apps/core-messaging/manage-inboxes.mdx

@@ -75,30 +75,51 @@ An inbox ID is limited to 256 inbox updates. Inbox updates include actions like:
 - Add an installation
 - Revoke an installation
 
-This means that one inbox ID can have up to 256 installations. When you add an inbox ID to a group, you are adding every installation as a member of the group. This means a group with an inbox that has 200+ installations can very quickly make a group size very large, which can have downstream performance implications.
+:::danger[CRITICAL FOR PRODUCTION]
 
-If an inbox reaches its limit of 256 inbox updates, the user must [rotate their inbox](#rotate-an-inbox-id) to continue using their identity with XMTP. Rotating the inbox permanently removes access to all existing conversations but allows the user to continue using their identity with new XMTP conversations.
+Inbox updates are cumulative and **cannot be reversed**. Revoking an installation counts as an update but does not decrease the total count. Once you've performed 256 updates, you've reached the permanent limit for that inbox.
+
+:::
+
+**What happens when you hit the limit:** If an inbox reaches its limit of 256 inbox updates, you may encounter an "inbox log is full" error. At this point, you must [rotate your inbox](#rotate-an-inbox-id) to continue using your identity with XMTP. Rotating the inbox permanently removes access to all existing conversations but allows you to continue using your identity with new XMTP conversations.
+
+**Why this limit exists:** All identity updates for an inbox must be fetched and validated by every other inbox that interacts with you on the XMTP network. In group conversations, this validation requirement multiplies. If multiple members have extensive identity update histories, it can significantly impact performance and message delivery speed.
 
 ### Installation limits
 
 XMTP enforces a 10-installation limit per inbox. When an inbox reaches 10 active installations, the user must revoke at least one installation before adding a new one. This limit serves two purposes:
 
 1. Prevents excessive group sizes: Since all installations in an inbox are added as group members, limiting installations keeps group sizes manageable and maintains performance.
-2. Protects against accidental exhaustion: The limit helps prevent users from accidentally reaching the 256-update threshold.
+2. Protects against accidental exhaustion: The limit helps prevent users from accidentally reaching the 256 inbox update threshold.
 
 :::warning[Important]
 
-Revoking an installation counts as one of the 256 inbox updates. This means frequently adding and revoking installations will still consume your update quota and could lead to reaching the limit prematurely.
+The only way to avoid consuming installation updates is to ensure your XMTP database is persisted and reloaded between app sessions and deployments. When you reuse an existing database, you maintain the same installation instead of creating a new one each time.
 
 :::
 
-The only way to prevent consuming installation updates is to ensure your XMTP database is persisted and reloaded between app sessions and deployments. When you reuse an existing database, you maintain the same installation instead of creating a new one each time.
+### Best Practices
+
+**For testing and development:**
+
+If you're developing or testing and frequently creating new installations, you can quickly exhaust your inbox update limit. To avoid this during development:
+
+1. Use persistent storage: Always configure your deployments to preserve the database between restarts
+2. Use a local node: Run XMTP locally so you can reset it when hitting limits
+3. Use different wallets for testing: Create separate test wallets rather than repeatedly creating installations with the same wallet
+4. Monitor your usage: Regularly check your inbox state to track how many updates you've used
 
 Have feedback about the inbox update and installation limits? We'd love to hear it. Post to the [XMTP Community Forums](https://community.xmtp.org/).
 
 ### Rotate an inbox ID
 
-When you create an inbox ID, there is a nonce on it that is used to create the ID. If an inbox reaches its inbox updates limit, you can increment the nonce and it will create a new inbox ID associated with the user's information.
+When you create an inbox ID, a [cryptographic nonce](https://en.wikipedia.org/wiki/Cryptographic_nonce) is used to create the ID. If an inbox reaches its inbox updates limit, you can increment the nonce to create a new inbox ID associated with the same wallet address.
+
+:::danger[CRITICAL FOR PRODUCTION]
+
+Rotating an inbox creates a completely new inbox ID. All conversations and message history from the old inbox will be permanently lost. Other users will need to start new conversations with your new inbox ID.
+
+:::
 
 ## Help users manage installations
 

docs/pages/fund-agents-apps/run-gateway.mdx

@@ -94,20 +94,9 @@ Every app and agent needs an XMTP Gateway Service.
 
 ### For browser and mobile client apps
 
-You must run the XMTP Gateway Service written in Go. Choose the option that works best for you:
+Use the [example gateway service repository](https://github.com/xmtp/gateway-service-example) as a starting point to build your own custom gateway with authentication
 
-**Option 1: Basic Docker image** (No Go knowledge required)
-
-- XMTP provides a Docker image that works out of the box
-- Authorizes all requests (add authentication for production)
-- Suitable for testing
-
-**Option 2: Custom implementation** (Go knowledge required)
-
-- Start with XMTP's Go implementation
-- Add your own authentication logic
-- Implement custom rate limiting
-- Required for apps with authentication needs
+For detailed implementation steps, see [Deploy your XMTP Gateway Service](#deploy-your-xmtp-gateway-service).
 
 ### For agents and Node.js apps
 
@@ -275,7 +264,7 @@ This identity will then be used for rate limiting, and will be passed to your `A
 
 :::code-group
 
-```go [IP Address]
+```go [IP address]
 //  We provide a simple implementation that uses the client's IP address to identify users. For a production application, you should limit requests to only users actually authenticated in your application.
 package main
 
@@ -393,7 +382,7 @@ func main() {
 
 ```
 
-```go [Rate Limiting]
+```go [Rate limiting]
 package main
 
 import (
@@ -478,22 +467,39 @@ func main() {
 
 ## Deploy your XMTP Gateway Service
 
-Deploy the XMTP Gateway Service on your infrastructure of choice, such as a container hosting service ($25-50/month minimum).
+:::tip[Example repo]
 
-We provide a Docker image that corresponds to the bare bones example above that you can run with the appropriate environment variables set in any hosting provider that supports Docker.
+You can start with the [example gateway service repository](https://github.com/xmtp/gateway-service-example).
 
-```bash [Bash]
-docker run -p 5050:5050 -p 5055:5055 -e XMTPD_PAYER_PRIVATE_KEY=... xmtp/xmtpd-gateway:main
-```
+:::
 
-Most production apps will require some level of customization to authorize user requests. You can fork our [example repository](https://github.com/xmtp/gateway-service-example), which includes a Dockerfile and a sample configuration.
+1. Fork or clone the repository.
+2. Add your own authentication logic.
+3. Configure your rate limits
+4. Deploy your custom image on your infrastructure of choice, such as a container hosting service ($25-50/month minimum).
+
+#### Additional recommendations
 
 The system is able to run without any external dependencies, but we recommend configuring a Redis instance to use for nonce management and rate limiting.
 
 If your XMTP Gateway Service goes down, messages will queue until it comes back online. Build redundancy, if needed.
 
 ## Test your XMTP Gateway Service
 
+You can use the prebuilt Docker image for local development and testing:
+
+```bash [Bash]
+docker run -p 5050:5050 -p 5055:5055 -e XMTPD_PAYER_PRIVATE_KEY=... xmtp/xmtpd-gateway:main
+```
+
+:::warning
+
+This pre-built image authorizes all requests without authentication. Never use it in production.
+
+:::
+
+### Test scenarios
+
 Here are some high priority scenarios to test:
 
 - Deploy and test XMTP Gateway Service