Skip to content

Commit 53d7425

Browse files
neekolasneekolas
authored
Merge pull request #61 from xmtp/nmolnar/conversations-docs
Conversations Docs
2 parents 46974c5 + 7e1509e commit 53d7425

File tree

1 file changed

+131
-14
lines changed

1 file changed

+131
-14
lines changed

‎README.md

+131-14
Original file line numberDiff line numberDiff line change
@@ -10,41 +10,158 @@ The XMTP SDK bundles the core code libraries, components, tools, documentation,
1010

1111
The API revolves around a network Client that allows retrieving and sending messages to other network participants. A Client must be connected to a wallet on startup. If this is the very first time the Client is created, the client will generate a key bundle that is used to encrypt and authenticate messages. The key bundle persists encrypted in local storage using a wallet signature. The public side of the key bundle is also regularly advertised on the network to allow parties to establish shared encryption keys. All this happens transparently, without requiring any additional code.
1212

13+
```ts
14+
import { Client } from 'xmtp-js'
15+
import { Wallet } from 'ethers'
16+
17+
// You'll want to replace this with a wallet from your application
18+
const wallet = Wallet.createRandom()
19+
// Create the client with your wallet. This will connect to the XMTP testnet by default
20+
const xmtp = await Client.create(wallet)
21+
// Start a conversation with Vitalik
22+
const conversation = await xmtp.conversations.newConversation(
23+
'0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
24+
)
25+
// Load all messages in the conversation
26+
const messages = await conversation.messages()
27+
// Send a message
28+
await conversation.send('gm')
29+
// Listen for new messages in the conversation
30+
for await (const message of conversation.streamMessages()) {
31+
console.log(`[${message.senderAddress}]: ${message.text}`)
32+
}
33+
```
34+
1335
### Creating a Client
1436

15-
A Client is created with `Client.create(wallet: ethers.Signer): Client` that requires passing in a connected Wallet. The Client will request a wallet signature in 2 cases:
37+
A Client is created with `Client.create(wallet: ethers.Signer): Promise<Client>` that requires passing in a connected Wallet. The Client will request a wallet signature in 2 cases:
1638

17-
1. to sign the newly generated key bundle, this happens only the very first time when key bundle is not found in storage
18-
2. to sign a random salt used to encrypt the key bundle in storage, this happens every time the Client is started (including the very first time)
39+
1. To sign the newly generated key bundle, this happens only the very first time when key bundle is not found in storage
40+
2. To sign a random salt used to encrypt the key bundle in storage, this happens every time the Client is started (including the very first time)
1941

2042
The Client will connect to XMTP testnet by default. CreateOptions can be used to override this and other parameters of the network connection.
2143

2244
Note that currently the Client uses browser's local storage, so starting it on a different device or browser and connecting to the same wallet will create a "split identity" situation where only one of the clients will be able to decrypt given incoming message depending on which of the advertised key bundles the sender chose to use. Similarly if local storage is cleared for whatever reason and a new key bundle is created, older messages encrypted with older bundles cannot be decrypted anymore and will cause the client to throw.
2345

24-
### Sending messages
46+
```ts
47+
import { Client } from 'xmtp-js'
48+
// Create the client with an `ethers.Signer` from your application
49+
const xmtp = await Client.create(wallet)
50+
```
2551

26-
To be able to send a message, the recipient must have already started their Client at least once and consequently advertised their key bundle on the network. Messages are addressed using wallet addresses. Message payload is a string but neither the SDK nor the network put any constraints on its contents or interpretation.
52+
### Conversations
2753

28-
First message and first response between two parties is sent to three separate topics:
54+
Most of the time, when interacting with the network, you'll want to do it through `conversations`.
2955

30-
1. sender's introduction topic
31-
2. recipient's introduction topic
32-
3. conversation topic shared by the sender and the recipient
56+
```ts
57+
import { Client } from 'xmtp-js'
58+
// Create the client with an `ethers.Signer` from your application
59+
const xmtp = await Client.create(wallet)
60+
const conversations = xmtp.conversations
61+
```
3362

34-
Any following messages are sent to the conversation topic only.
63+
#### List existing conversations
3564

36-
The introduction topics allow the participants to reconstruct the list of conversations that they participate(d) in.
65+
You can get a list of all conversations that have had 1 or more messages exchanged in the last 30 days.
3766

38-
The conversation topics carry the contents of the conversations.
67+
```ts
68+
const allConversations = await xmtp.conversations.list()
69+
// Say gm to everyone you've been chatting with
70+
for (const conversation of allConversations) {
71+
console.log(`Saying GM to ${conversation.peerAddress}`)
72+
await conversation.send('gm')
73+
}
74+
```
75+
76+
#### Listen for new conversations
77+
78+
You can also listen for new conversations being started in real-time. This will allow applications to display incoming messages from new contacts.
79+
80+
_Warning: this stream will continue infinitely. To end the stream you can either break from the loop, or call `await stream.return()`_
81+
82+
```ts
83+
const stream = xmtp.conversations.stream()
84+
for await (const conversation of stream) {
85+
console.log(`New conversation started with ${conversation.peerAddress}`)
86+
// Say hello to your new friend
87+
await conversation.send('Hi there!')
88+
// Break from the loop to stop listening
89+
break
90+
}
91+
```
92+
93+
#### Start a new conversation
94+
95+
You can create a new conversation with any Ethereum address on the XMTP network.
96+
97+
```ts
98+
const newConversation = await xmtp.conversations.newConversation(
99+
'0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
100+
)
101+
```
102+
103+
#### Sending messages
104+
105+
To be able to send a message, the recipient must have already started their Client at least once and consequently advertised their key bundle on the network. Messages are addressed using wallet addresses. Message payload is a string but neither the SDK nor the network put any constraints on its contents or interpretation.
39106

40-
### Receiving messages
107+
```ts
108+
const conversation = await xmtp.conversations.newConversation(
109+
'0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
110+
)
111+
await conversation.send('Hello world')
112+
```
41113

42-
There are two types of primitives for retrieving messages from the network. Use the `list` methods to retrieve past messages that were stored by the network. Use the `stream` methods to listen to new messages using asynchronous iteration. Both primitive types have variants for listing or streaming the introduction topics (to manage the list of conversations) or the conversation topics (to manage the contents of the conversations).
114+
#### List messages in a conversation
115+
116+
You can receive the complete message history by calling `conversation.messages()`
117+
118+
```ts
119+
for (const conversation of await xmtp.conversations.list()) {
120+
// All parameters are optional and can be omitted
121+
const opts = {
122+
// Only show messages from last 24 hours
123+
startTime: new Date(new Date().setDate(new Date().getDate() - 1)),
124+
endTime: new Date(),
125+
}
126+
const messagesInConversation = await conversation.messages(opts)
127+
}
128+
```
129+
130+
#### Listen for new messages in a conversation
131+
132+
You can listen for any new messages (incoming or outgoing) in a conversation by calling `conversation.streamMessages()`.
43133

44134
A successfully received message (that makes it through the decoding and decryption without throwing) can be trusted to be authentic, i.e. that it was sent by the owner of the `message.senderAddress` wallet and that it wasn't modified in transit. The `message.sent` timestamp can be trusted to have been set by the sender.
45135

46136
The Stream returned by the `stream` methods is an asynchronous iterator and as such usable by a for-await-of loop. Note however that it is by its nature infinite, so any looping construct used with it will not terminate, unless the termination is explicitly initiated (by breaking the loop or by an external call to `Stream.return()`)
47137

138+
```ts
139+
const conversation = await xmtp.conversations.newConversation(
140+
'0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
141+
)
142+
for await (const message of conversation.streamMessages()) {
143+
if (message.senderAddress === xmtp.address) {
144+
// This message was sent from me
145+
continue
146+
}
147+
console.log(`New message from ${message.senderAddress}: ${message.text}`)
148+
}
149+
```
150+
151+
#### Under the hood
152+
153+
Using `xmtp.conversations` hides the details of this, but for the curious this is how sending a message on XMTP works. The first message and first response between two parties is sent to three separate topics:
154+
155+
1. Sender's introduction topic
156+
2. Recipient's introduction topic
157+
3. Conversation topic shared by the sender and the recipient
158+
159+
This is used to establish a shared secret and negotiate a topic to communicate on. Any following messages are sent to the conversation topic only.
160+
161+
The introduction topics allow the participants to reconstruct the list of conversations that they participate(d) in.
162+
163+
The conversation topics carry the contents of the conversations.
164+
48165
## Developing
49166

50167
### Auto-releasing and commit conventions

0 commit comments

Comments
 (0)