From 04eab292b9a8dd50287dc505f284220c16bff22f Mon Sep 17 00:00:00 2001 From: Naomi Plasterer Date: Wed, 6 Nov 2024 18:43:31 -0800 Subject: [PATCH] update the read me --- README.md | 194 ++++++------------ .../org/xmtp/android/example/MainViewModel.kt | 12 -- .../org/xmtp/android/library/Conversation.kt | 10 +- .../main/java/org/xmtp/android/library/Dm.kt | 2 +- .../java/org/xmtp/android/library/Group.kt | 2 +- 5 files changed, 70 insertions(+), 150 deletions(-) diff --git a/README.md b/README.md index 61bf138a2..08dff8fd6 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # xmtp-android -![Test](https://github.com/xmtp/xmtp-android/actions/workflows/test.yml/badge.svg) ![Lint](https://github.com/xmtp/xmtp-android/actions/workflows/lint.yml/badge.svg) ![Status](https://img.shields.io/badge/Project_Status-Production-31CA54) +![Test](https://github.com/xmtp/xmtp-android/actions/workflows/test.yml/badge.svg) ![Lint](https://github.com/xmtp/xmtp-android/actions/workflows/lint.yml/badge.svg) ![Status](https://img.shields.io/badge/Feature_status-Alpha-orange) `xmtp-android` provides a Kotlin implementation of an XMTP message API client for use with Android apps. @@ -25,7 +25,7 @@ To learn about example app push notifications, see [Enable the quickstart app to ## Install from Maven Central -You can find the latest package version on [Maven Central](https://central.sonatype.com/artifact/org.xmtp/android/0.0.5/versions). +You can find the latest package version on [Maven Central](https://central.sonatype.com/artifact/org.xmtp/android/3.0.0/versions). ```gradle implementation 'org.xmtp:android:X.X.X' @@ -33,73 +33,67 @@ You can find the latest package version on [Maven Central](https://central.sonat ## Usage overview -The XMTP message API revolves around a message API client (client) that allows retrieving and sending messages to other XMTP network participants. A client must connect to a wallet app 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 the network using an account signature. The public side of the key bundle is also regularly advertised on the network to allow parties to establish shared encryption keys. All of this happens transparently, without requiring any additional code. +The XMTP message API revolves around a message API client (client) that allows retrieving and sending messages to other XMTP network participants. A client must connect to a wallet app on startup. If this is the very first time the client is created, the client will generate a identity with a encrypted local database to store and retrieve messages. Each additional log in will create a new installation if a local database is not present. ```kotlin // You'll want to replace this with a wallet from your application. val account = PrivateKeyBuilder() +// A key to encrypt the local database +val encryptionKey = SecureRandom().generateSeed(32) + +// Application context for creating the local database +val context = getApplication() + +// The required client options +val clientOptions = ClientOptions( + ClientOptions.Api(XMTPEnvironment.DEV, isSecure = true), + dbEncryptionKey = encryptionKey, + appContext = context, +) + // Create the client with your wallet. This will connect to the XMTP `dev` network by default. // The account is anything that conforms to the `XMTP.SigningKey` protocol. -val client = Client().create(account = account) +val client = Client().create(account = account, options = clientOptions) -// Start a conversation with XMTP +// Start a dm conversation val conversation = client.conversations.newConversation("0x3F11b27F323b62B159D2642964fa27C46C841897") +// Or a group conversation +val groupConversation = client.conversations.newGroup(listOf("0x3F11b27F323b62B159D2642964fa27C46C841897")) -// Load all messages in the conversation +// Load all messages in the conversations val messages = conversation.messages() + // Send a message conversation.send(text = "gm") + // Listen for new messages in the conversation conversation.streamMessages().collect { - print("${message.senderAddress}: ${message.body}") + print("${it.senderAddress}: ${it.body}") } ``` -## Use local storage - -> **Important** -> If you are building a production-grade app, be sure to use an architecture that includes a local cache backed by an XMTP SDK. - -To learn more, see [Use a local cache](https://xmtp.org/docs/build/local-first). - ## Create a client -A client is created with `Client().create(account: SigningKey): Client` that requires passing in an object capable of creating signatures on your behalf. The client will request a signature in two cases: - -1. To sign the newly generated key bundle. This happens only the very first time when a key bundle is not found in storage. -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. +A client is created with `Client().create(account: SigningKey, options: ClientOptions): Client` that requires passing in an object capable of creating signatures on your behalf. The client will request a signature for any new installation. > **Note** > The client connects to the XMTP `dev` environment by default. [Use `ClientOptions`](#configure-the-client) to change this and other parameters of the network connection. ```kotlin // Create the client with a `SigningKey` from your app -val options = ClientOptions(api = ClientOptions.Api(env = XMTPEnvironment.PRODUCTION, isSecure = true)) +val options = ClientOptions(api = ClientOptions.Api(env = XMTPEnvironment.PRODUCTION, isSecure = true), dbEncryptionKey = encryptionKey, appContext = context) val client = Client().create(account = account, options = options) ``` -### Create a client from saved keys +### Create a client from saved encryptionKey -You can save your keys from the client via the `privateKeyBundle` property: +You can save your encryptionKey for the local database and build the client via address: ```kotlin // Create the client with a `SigningKey` from your app -val options = ClientOptions(api = ClientOptions.Api(env = XMTPEnvironment.PRODUCTION, isSecure = true)) -val client = Client().create(account = account, options = options) - -// Get the key bundle -val keys = client.privateKeyBundleV1 - -// Serialize the key bundle and store it somewhere safe -val serializedKeys = PrivateKeyBundleV1Builder.encodeData(v1) -``` - -Once you have those keys, you can create a new client with `Client().buildFrom()`: - -```kotlin -val keys = PrivateKeyBundleV1Builder.fromEncodedData(serializedKeys) -val client = Client().buildFrom(bundle = keys, options = options) +val options = ClientOptions(api = ClientOptions.Api(env = XMTPEnvironment.PRODUCTION, isSecure = true), dbEncryptionKey = encryptionKey, appContext = context) +val client = Client().build(address = account.address, options = options) ``` ### Configure the client @@ -107,44 +101,46 @@ val client = Client().buildFrom(bundle = keys, options = options) You can configure the client with these parameters of `Client.create`: | Parameter | Default | Description | -| ---------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| ---------- |-------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | env | `DEV` | Connect to the specified XMTP network environment. Valid values include `DEV`, `.PRODUCTION`, or `LOCAL`. For important details about working with these environments, see [XMTP `production` and `dev` network environments](#xmtp-production-and-dev-network-environments). | +| appContext | `REQUIRED` | The application context used to create and access the local database. | +| dbEncryptionKey | `REQUIRED` | A 32 ByteArray used to encrypt the local database. | +| historySyncUrl | `https://message-history.dev.ephemera.network/` | The history sync url used to specify where history can be synced from other devices on the network. | | appVersion | `undefined` | Add a client app version identifier that's included with API requests.
For example, you can use the following format: `appVersion: APP_NAME + '/' + APP_VERSION`.
Setting this value provides telemetry that shows which apps are using the XMTP client SDK. This information can help XMTP developers provide app support, especially around communicating important SDK updates, including deprecations and required upgrades. | **Configure `env`** -```kotlin -// Configure the client to use the `production` network -val options = ClientOptions(api = ClientOptions.Api(env = XMTPEnvironment.PRODUCTION, isSecure = true)) -val client = Client().create(account = account, options = options) -``` - -> **Note** -> The `apiUrl`, `keyStoreType`, `codecs`, and `maxContentSize` parameters from the XMTP client SDK for JavaScript (xmtp-js) are not yet supported. - ## Handle conversations Most of the time, when interacting with the network, you'll want to do it through `conversations`. Conversations are between two accounts. +### List all dm & group conversations + +If your app would like to handle groups and dms differently you can check whether a conversation is a dm or group for the type ```kotlin -// Create the client with a wallet from your app -val client = Client().create(account = account) val conversations = client.conversations.list() -``` -### List existing conversations +for (conversation in conversations) { + when (conversation.type) { + is Group -> // Handle group + is Dm -> // Handle dm + } +} +``` -You can get a list of all conversations that have one or more messages. +### List all groups ```kotlin -val allConversations = client.conversations.list() +val conversations = client.conversations.listGroups() +``` -for (conversation in allConversations) { - print("Saying GM to ${conversation.peerAddress}") - conversation.send(text = "gm") -} +### List all dms + +```kotlin +val conversations = client.conversations.listDms() ``` + These conversations include all conversations for a user **regardless of which app created the conversation.** This functionality provides the concept of an [interoperable inbox](https://xmtp.org/docs/concepts/interoperable-inbox), which enables a user to access all of their conversations in any app built with XMTP. ### Listen for new conversations @@ -164,12 +160,16 @@ client.conversations.stream().collect { You can create a new conversation with any Ethereum address on the XMTP network. ```kotlin -val newConversation = client.conversations.newConversation("0x3F11b27F323b62B159D2642964fa27C46C841897") +val newDm = client.conversations.newConversation("0x3F11b27F323b62B159D2642964fa27C46C841897") +``` + +```kotlin +val newGroup = client.conversations.newGroup("listOf(0x3F11b27F323b62B159D2642964fa27C46C841897)") ``` ### Send messages -To be able to send a message, the recipient must have already created a client at least once and consequently advertised their key bundle on the network. Messages are addressed using account addresses. In this example, the message payload is a plain text string. +To be able to send a message, the recipient must have already created a client at least once. Messages are addressed using account addresses. In this example, the message payload is a plain text string. ```kotlin val conversation = client.conversations.newConversation("0x3F11b27F323b62B159D2642964fa27C46C841897") @@ -183,9 +183,7 @@ To learn how to send other types of content, see [Handle different content types You can receive the complete message history in a conversation by calling `conversation.messages()` ```kotlin -for (conversation in client.conversations.list()) { - val messagesInConversation = conversation.messages() -} + conversation.messages() ``` ### List messages in a conversation with pagination @@ -193,10 +191,8 @@ for (conversation in client.conversations.list()) { It may be helpful to retrieve and process the messages in a conversation page by page. You can do this by calling `conversation.messages(limit: Int, before: Date)` which will return the specified number of messages sent before that time. ```kotlin -val conversation = client.conversations.newConversation("0x3F11b27F323b62B159D2642964fa27C46C841897") - val messages = conversation.messages(limit = 25) -val nextPage = conversation.messages(limit = 25, before = messages[0].sent) +val nextPage = conversation.messages(limit = 25, beforeNs = messages[0].sentNs) ``` ### Listen for new messages in a conversation @@ -208,8 +204,6 @@ A successfully received message (that makes it through the decoding and decrypti The flow returned by the `stream` methods is an asynchronous data stream that sequentially emits values and completes normally or with an exception. ```kotlin -val conversation = client.conversations.newConversation("0x3F11b27F323b62B159D2642964fa27C46C841897") - conversation.streamMessages().collect { if (it.senderAddress == client.address) { // This message was sent from me @@ -219,58 +213,6 @@ conversation.streamMessages().collect { } ``` -### Decode a single message - -You can decode a single `Envelope` from XMTP using the `decode` method: - -```kotlin -val conversation = client.conversations.newConversation("0x3F11b27F323b62B159D2642964fa27C46C841897") - -// Assume this function returns an Envelope that contains a message for the above conversation -val envelope = getEnvelopeFromXMTP() - -val decodedMessage = conversation.decode(envelope) -``` - -### Serialize/Deserialize conversations - -You can save a conversation object locally using its `encodedContainer` property. This returns a `ConversationContainer` object which conforms to `Codable`. - -```kotlin -// Get a conversation -val conversation = client.conversations.newConversation("0x3F11b27F323b62B159D2642964fa27C46C841897") - -// Dump it to JSON -val gson = GsonBuilder().create() -val data = gson.toJson(conversation) - -// Get it back from JSON -val containerAgain = gson.fromJson(data.toString(StandardCharsets.UTF_8), ConversationV2Export::class.java) - -// Get an actual Conversation object like we had above -val decodedConversation = containerAgain.decode(client) -decodedConversation.send(text = "hi") -``` - -### Cache conversations - -As a performance optimization, you may want to persist the list of conversations in your application outside of the SDK to speed up the first call to `client.conversations.list()`. - -The exported conversation list contains encryption keys for any V2 conversations included in the list. As such, you should treat it with the same care that you treat private keys. - -You can get a JSON serializable list of conversations by calling: - -```kotlin -val client = Client().create(wallet) -val conversations = client.conversations.export() -saveConversationsSomewhere(JSON.stringify(conversations)) -// To load the conversations in a new SDK instance you can run: - -val client = Client.create(wallet) -val conversations = JSON.parse(loadConversationsFromSomewhere()) -val client.importConversation(conversations) -``` - ## Request and respect user consent ![Feature status](https://img.shields.io/badge/Feature_status-Alpha-orange) @@ -309,16 +251,6 @@ As shown in the example above, you must provide a `contentFallback` value. Use i Beyond this, custom codecs and content types may be proposed as interoperable standards through XRCs. To learn more about the custom content type proposal process, see [XIP-5](https://github.com/xmtp/XIPs/blob/main/XIPs/xip-5-message-content-types.md). -## Compression - -Message content can be optionally compressed using the compression option. The value of the option is the name of the compression algorithm to use. Currently supported are gzip and deflate. Compression is applied to the bytes produced by the content codec. - -Content will be decompressed transparently on the receiving end. Note that Client enforces maximum content size. The default limit can be overridden through the ClientOptions. Consequently a message that would expand beyond that limit on the receiving end will fail to decode. - -```kotlin -conversation.send(text = '#'.repeat(1000), options = ClientOptions.Api(compression = EncodedContentCompression.GZIP)) -``` - ## 🏗 Breaking revisions Because `xmtp-android` is in active development, you should expect breaking revisions that might require you to adopt the latest SDK release to enable your app to continue working as expected. @@ -334,9 +266,9 @@ Older versions of the SDK will eventually be deprecated, which means: The following table provides the deprecation schedule. -| Announced | Effective | Minimum Version | Rationale | -| -------------------------------------------------------------------- | --------- | --------------- | --------- | -| There are no deprecations scheduled for `xmtp-android` at this time. | | | | +| Announced | Effective | Minimum Version | Rationale | +|------------------------|---------------|-----------------|---------------------------------------------------------------------------------------------------------------------------------------| +| No more support for V2 | March 1, 2025 | 3.0.0 | In a move towards better security with MLS and the ability to decentralize we will be shutting down V2 and moving entirely to V3 MLS. | Bug reports, feature requests, and PRs are welcome in accordance with these [contribution guidelines](https://github.com/xmtp/xmtp-android/blob/main/CONTRIBUTING.md). diff --git a/example/src/main/java/org/xmtp/android/example/MainViewModel.kt b/example/src/main/java/org/xmtp/android/example/MainViewModel.kt index ec57cb807..bbaae6a42 100644 --- a/example/src/main/java/org/xmtp/android/example/MainViewModel.kt +++ b/example/src/main/java/org/xmtp/android/example/MainViewModel.kt @@ -46,20 +46,8 @@ class MainViewModel : ViewModel() { val listItems = mutableListOf() try { val conversations = ClientManager.client.conversations.list() - val hmacKeysResult = ClientManager.client.conversations.getHmacKeys() val subscriptions: MutableList = conversations.map { - val hmacKeys = hmacKeysResult.hmacKeysMap - val result = hmacKeys[it.topic]?.valuesList?.map { hmacKey -> - Service.Subscription.HmacKey.newBuilder().also { sub_key -> - sub_key.key = hmacKey.hmacKey - sub_key.thirtyDayPeriodsSinceEpoch = hmacKey.thirtyDayPeriodsSinceEpoch - }.build() - } - Service.Subscription.newBuilder().also { sub -> - if (!result.isNullOrEmpty()) { - sub.addAllHmacKeys(result) - } sub.topic = it.topic }.build() }.toMutableList() diff --git a/library/src/main/java/org/xmtp/android/library/Conversation.kt b/library/src/main/java/org/xmtp/android/library/Conversation.kt index ca66d3a68..bce90bddf 100644 --- a/library/src/main/java/org/xmtp/android/library/Conversation.kt +++ b/library/src/main/java/org/xmtp/android/library/Conversation.kt @@ -10,13 +10,13 @@ sealed class Conversation { data class Group(val group: org.xmtp.android.library.Group) : Conversation() data class Dm(val dm: org.xmtp.android.library.Dm) : Conversation() - enum class Version { GROUP, DM } + enum class Type { GROUP, DM } - val version: Version + val type: Type get() { return when (this) { - is Group -> Version.GROUP - is Dm -> Version.DM + is Group -> Type.GROUP + is Dm -> Type.DM } } @@ -72,7 +72,7 @@ sealed class Conversation { } } - suspend fun prepareMessage(content: T, options: SendOptions? = null): String { + fun prepareMessage(content: T, options: SendOptions? = null): String { return when (this) { is Group -> group.prepareMessage(content, options) is Dm -> dm.prepareMessage(content, options) diff --git a/library/src/main/java/org/xmtp/android/library/Dm.kt b/library/src/main/java/org/xmtp/android/library/Dm.kt index 8b391c0cd..69552596c 100644 --- a/library/src/main/java/org/xmtp/android/library/Dm.kt +++ b/library/src/main/java/org/xmtp/android/library/Dm.kt @@ -81,7 +81,7 @@ class Dm(val client: Client, private val libXMTPGroup: FfiConversation) { return encoded } - suspend fun prepareMessage(content: T, options: SendOptions? = null): String { + fun prepareMessage(content: T, options: SendOptions? = null): String { if (consentState() == ConsentState.UNKNOWN) { updateConsentState(ConsentState.ALLOWED) } diff --git a/library/src/main/java/org/xmtp/android/library/Group.kt b/library/src/main/java/org/xmtp/android/library/Group.kt index b62365cec..e1f9c93f0 100644 --- a/library/src/main/java/org/xmtp/android/library/Group.kt +++ b/library/src/main/java/org/xmtp/android/library/Group.kt @@ -98,7 +98,7 @@ class Group(val client: Client, private val libXMTPGroup: FfiConversation) { return encoded } - suspend fun prepareMessage(content: T, options: SendOptions? = null): String { + fun prepareMessage(content: T, options: SendOptions? = null): String { if (consentState() == ConsentState.UNKNOWN) { updateConsentState(ConsentState.ALLOWED) }