Merge upstream main branch

Author: humanagent

.env.example

@@ -1,5 +1,6 @@
 WALLET_KEY= # the private key of the wallet
 ENCRYPTION_KEY= # a second random 32 bytes encryption key for local db encryption
+XMTP_ENV=dev # the environment to use, dev, local or production
 
 # GPT agent example
 OPENAI_API_KEY= # the API key for the OpenAI 

README.md

@@ -18,19 +18,38 @@ This repository contains examples of agents that use the [XMTP](https://docs.xmt
 
 To run your XMTP agent, you must create a `.env` file with the following variables:
 
-```bash
+```tsx
 WALLET_KEY= # the private key of the wallet
 ENCRYPTION_KEY= # encryption key for the local database
 ```
 
 You can generate random keys with the following command:
 
-```bash
-yarn gen:keys
+```tsx
+yarn gen:keys <name>
 ```
 
 > [!WARNING]
-> Running the `gen:keys` script will overwrite the existing `.env` file.
+> Running the `gen:keys` or `gen:keys <name>` command will append keys to your existing `.env` file.
+
+### Work in local network
+
+`Dev` and `production` networks are hosted by XMTP, while `local` network is hosted by yourself. Use local network for development purposes only.
+
+- 1. Install docker
+- 2. Start the XMTP service and database
+
+```tsx
+./dev/up
+```
+
+- 3. Change the .env file to use the local network
+
+```tsx
+XMTP_ENV = local;
+```
+
+## Concepts
 
 ### Fetching messages
 
@@ -52,31 +71,51 @@ await client.conversations.sync();
 await client.conversations.messages();
 ```
 
-### Working with addresses
-
-Conversations in XMTP can be `DMs` or `Groups`. The underlying technicalities are the same, but DMs are essentially groups locked between two users that can be reused - basically a fixed group of 2. This is how MLS works.
+### Conversations can be of type `Group` or `Dm`
 
-Each member of a conversation has the following properties:
+The new `Group` and `Dm` classes extend the `Conversation` class and provide specific functionality based on the conversation type.
 
 ```tsx
-inboxId: string; // unique identifier from the XMTP network
-accountAddresses: Array<string>; // ethereum network addresses
-installationIds: Array<string>; // How many active devices the user has
-permissionLevel: PermissionLevel; // In the context of a group, if it's admin or not
-consentState: ConsentState; // If it's blocked or allowed via consent
+const conversations: (Group | Dm)[] = await client.conversations.list();
+
+for (const conversation of conversations) {
+  // narrow the type to Group to access the group name
+  if (conversation instanceof Group) {
+    console.log(group.name);
+  }
+
+  // narrow the type to Dm to access the peer inboxId
+  if (conversation instanceof Dm) {
+    console.log(conversation.peerInboxId);
+  }
+}
 ```
 
-To fetch an ethereum address in a DM, you can use a script like the following:
+### Working with addresses
+
+Because XMTP is interoperable, you may interact with inboxes that are not on your app. In these scenarios, you will need to find the appropriate inbox ID or address.
 
 ```tsx
-const address =
-  (await group.members?.find(
-    (member: any) => member.inboxId === dm.dmPeerInboxId,
-  )?.accountAddresses[0]) || "";
-```
+// get an inbox ID from an address
+const inboxId = await getInboxIdForIdentifier({
+  identifier: "0x1234567890abcdef1234567890abcdef12345678",
+  identifierKind: IdentifierKind.Ethereum,
+});
+
+// find the addresses associated with an inbox ID
+const inboxState = await client.inboxStateFromInboxIds([inboxId]);
+
+interface InboxState {
+  inboxId: string;
+  recoveryIdentifier: Identifier;
+  installations: Installation[];
+  identifiers: Identifier[];
+}
 
-> [!WARNING]
-> XMTP is working on integrating passkeys as a pillar of identity. Expect a breaking change soon as XMTP prepares for the first v3 stable release.
+const addresses = inboxState.identifiers
+  .filter((i) => i.identifierKind === IdentifierKind.Ethereum)
+  .map((i) => i.identifier);
+```
 
 ## Web inbox
 
@@ -96,6 +135,7 @@ Interact with the XMTP network using [xmtp.chat](https://xmtp.chat), the officia
 
 Examples integrating XMTP with external libraries from the ecosystem
 
-- [grok](/integrations/grok/): Integrate XMTP to the Grok API
+- [grok](/integrations/grok/): Integrate your agent with the Grok API
+- [gaia](/integrations/gaia/): Integrate with the Gaia API
 
 > See all the available [integrations](/integrations/).

dev/compose

@@ -0,0 +1,4 @@
+#!/bin/bash
+set -eou pipefail
+
+docker compose -f dev/docker-compose.yml -p "xmtp-js" "$@"

dev/docker-compose.yml

@@ -0,0 +1,41 @@
+services:
+  node:
+    image: xmtp/node-go:latest
+    platform: linux/amd64
+    environment:
+      - GOWAKU-NODEKEY=8a30dcb604b0b53627a5adc054dbf434b446628d4bd1eccc681d223f0550ce67
+    command:
+      - --store.enable
+      - --store.db-connection-string=postgres://postgres:xmtp@db:5432/postgres?sslmode=disable
+      - --store.reader-db-connection-string=postgres://postgres:xmtp@db:5432/postgres?sslmode=disable
+      - --mls-store.db-connection-string=postgres://postgres:xmtp@mlsdb:5432/postgres?sslmode=disable
+      - --mls-validation.grpc-address=validation:50051
+      - --api.enable-mls
+      - --wait-for-db=30s
+      - --api.authn.enable
+    ports:
+      - 5555:5555
+      - 5556:5556
+    depends_on:
+      - db
+      - mlsdb
+      - validation
+
+  validation:
+    image: ghcr.io/xmtp/mls-validation-service:main
+    platform: linux/amd64
+
+  db:
+    image: postgres:13
+    environment:
+      POSTGRES_PASSWORD: xmtp
+
+  mlsdb:
+    image: postgres:13
+    environment:
+      POSTGRES_PASSWORD: xmtp
+
+  upload-service:
+    build: ./uploadService
+    ports:
+      - 3000:3000

dev/down

@@ -0,0 +1,5 @@
+#!/bin/bash
+set -eou pipefail
+script_dir="$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
+
+"${script_dir}"/compose down

dev/up

@@ -0,0 +1,6 @@
+#!/bin/bash
+set -eou pipefail
+script_dir="$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
+
+"${script_dir}"/compose pull
+"${script_dir}"/compose up -d --wait

dev/uploadService/Dockerfile

@@ -0,0 +1,15 @@
+# Fetching the minified node image on apline linux
+FROM node:18.19-slim
+
+WORKDIR /uploadService
+COPY . .
+
+RUN apt-get update && \
+  apt-get install -y openssl && \
+  openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -sha256 -days 3650 -subj /CN=localhost -out cert.pem
+
+RUN npm install
+
+CMD ["node", "index.js"]
+
+EXPOSE 3000

dev/uploadService/index.js

@@ -0,0 +1,36 @@
+const fs = require("fs");
+const https = require("https");
+const express = require("express");
+const bodyParser = require("body-parser");
+const app = express();
+const port = 3000;
+
+const key = fs.readFileSync("key.pem", "utf-8");
+const cert = fs.readFileSync("cert.pem", "utf-8");
+
+const UPLOADS = {};
+
+app.use(bodyParser.raw({ type: "application/octet-stream" }));
+
+app.get("/:path", (req, res) => {
+  const path = req.params.path;
+  console.log(`GET /${path}`);
+  const file = UPLOADS[path];
+  if (file) {
+    res.header("Content-Type", "application/octet-stream");
+    res.send(file);
+  } else {
+    console.log(`Upload path found: ${path}`);
+  }
+});
+
+app.post("/:path", (req, res) => {
+  const path = req.params.path;
+  console.log(`POST /${path}`);
+  UPLOADS[path] = req.body;
+  res.sendStatus(200);
+});
+
+https.createServer({ key, cert }, app).listen(port, () => {
+  console.log(`Upload service listening on port ${port}`);
+});

dev/uploadService/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "uploadservice",
+  "version": "0.0.0",
+  "private": true,
+  "main": "index.js",
+  "scripts": {
+    "start": "node index.js"
+  },
+  "dependencies": {
+    "body-parser": "^1.20.2",
+    "express": "^4.18.2"
+  }
+}

examples/gated-group/README.md

@@ -20,9 +20,6 @@ You can generate random keys with the following command:
 yarn gen:keys
 ```
 
-> [!WARNING]
-> Running the `gen:keys` script will overwrite the existing `.env` file.
-
 ## Start the XMTP agent
 
 Start your XMTP client and begin listening to messages. The bot responds to the following commands:
@@ -33,7 +30,7 @@ Start your XMTP client and begin listening to messages. The bot responds to the
 if (message.content === "/create") {
   console.log("Creating group");
   const group = await client.conversations.newGroup([]);
-  await group.addMembersByInboxId([message.senderInboxId]);
+  await group.addMembers([message.senderInboxId]);
   await group.addSuperAdmin(message.senderInboxId);
 
   await conversation.send(

examples/gated-group/index.ts

@@ -1,4 +1,4 @@
-import { Client, type XmtpEnv } from "@xmtp/node-sdk";
+import { Client, type Group, type XmtpEnv } from "@xmtp/node-sdk";
 import { Alchemy, Network } from "alchemy-sdk";
 import { createSigner, getEncryptionKeyFromHex } from "@/helpers";
 
@@ -24,8 +24,8 @@ if (!ENCRYPTION_KEY) {
 const signer = createSigner(WALLET_KEY);
 const encryptionKey = getEncryptionKeyFromHex(ENCRYPTION_KEY);
 
-/* Set the environment to dev or production */
-const env: XmtpEnv = "dev";
+/* Set the environment to local, dev or production */
+const env: XmtpEnv = process.env.XMTP_ENV as XmtpEnv;
 
 async function main() {
   console.log(`Creating client on the '${env}' network...`);
@@ -36,8 +36,11 @@ async function main() {
   console.log("Syncing conversations...");
   await client.conversations.sync();
 
+  const identifier = await signer.getIdentifier();
+  const address = identifier.identifier;
+
   console.log(
-    `Agent initialized on ${client.accountAddress}\nSend a message on http://xmtp.chat/dm/${client.accountAddress}`,
+    `Agent initialized on ${address}\nSend a message on http://xmtp.chat/dm/${address}?env=${env}`,
   );
 
   console.log("Waiting for messages...");
@@ -56,8 +59,8 @@ async function main() {
       `Received message: ${message.content as string} by ${message.senderInboxId}`,
     );
 
-    const conversation = client.conversations.getConversationById(
-      message.conversationId,
+    const conversation = client.conversations.getDmByInboxId(
+      message.senderInboxId,
     );
 
     if (!conversation) {
@@ -74,7 +77,7 @@ async function main() {
       const group = await client.conversations.newGroup([]);
       console.log("Group created", group.id);
       // First add the sender to the group
-      await group.addMembersByInboxId([message.senderInboxId]);
+      await group.addMembers([message.senderInboxId]);
       // Then make the sender a super admin
       await group.addSuperAdmin(message.senderInboxId);
       console.log(
@@ -98,7 +101,7 @@ async function main() {
         await conversation.send("Please provide a group id");
         return;
       }
-      const group = client.conversations.getConversationById(groupId);
+      const group = await client.conversations.getConversationById(groupId);
       if (!group) {
         await conversation.send("Please provide a valid group id");
         return;
@@ -113,7 +116,7 @@ async function main() {
         console.log("User can't be added to the group");
         return;
       } else {
-        await group.addMembers([walletAddress]);
+        await (group as Group).addMembers([walletAddress]);
         await conversation.send(
           `User added to the group\n- Group ID: ${groupId}\n- Wallet Address: ${walletAddress}`,
         );

examples/gm/README.md

@@ -25,8 +25,8 @@ if (!ENCRYPTION_KEY) {
 const signer = createSigner(WALLET_KEY);
 const encryptionKey = getEncryptionKeyFromHex(ENCRYPTION_KEY);
 
-/* Set the environment to dev or production */
-const env: XmtpEnv = "dev";
+/* Set the environment to local, dev or production */
+const env: XmtpEnv = process.env.XMTP_ENV as XmtpEnv;
 
 async function main() {
   console.log(`Creating client on the '${env}' network...`);
@@ -36,8 +36,10 @@ async function main() {
   /* Sync the conversations from the network to update the local db */
   await client.conversations.sync();
 
+  const identifier = await signer.getIdentifier();
+  const address = identifier.identifier;
   console.log(
-    `Agent initialized on ${client.accountAddress}\nSend a message on http://xmtp.chat/dm/${client.accountAddress}?env=${env}`,
+    `Agent initialized on ${address}\nSend a message on http://xmtp.chat/dm/${address}?env=${env}`,
   );
 
   console.log("Waiting for messages...");