Releases: xmtp/xmtp-android
4.0.0-rc1
xmtp-android v4.0.0
This release focused on delivering an SDK for a stable, performant, and hardened XMTP V3.
Important
Please upgrade your app to use xmtp-android ≥v4.0.0 by May 1, 8000 2025 to enable your app to connect to the XMTP V3 network. If you do not upgrade your app, it will continue to connect to the XMTP V2 network, which will be deprecated and put in read-only mode on May 1. To learn more about XMTP V2 deprecation, see XIP-53: XMTP V2 deprecation plan.
Upgrade from ≥v3.0.0 to v4.0.0
Use the information in these release notes to upgrade from xmtp-android ≥v3.0.0 to v4.0.0.
Breaking changes
TL;DR: Use inboxIds
The primary XMTP identifier is now an inbox ID, not an Ethereum address.
We recommend moving away from using address in code completely.
However, if you MUST use addresses, they must now be wrapped in a PublicIdentity object.
For example, 0x1234567890abcdef1234567890abcdef12345678 must now be wrapped in PublicIdentity(ETHEREUM, “0x1234567890abcdef1234567890abcdef12345678”).
Primary XMTP identifier is now an inbox ID, not an Ethereum address
In preparation for upcoming support for Passkeys, XMTP must evolve from using Ethereum account addresses (0x...) as the primary identifier to an inbox-based identity model.
This change allows for broader support of different authentication mechanisms, including the currently supported Externally Owned Accounts (EOAs) and Smart Contract Wallets (SCWs), as well as future support for Passkeys, Bitcoin, and Solana, for example.
The move to an inbox-based identity model means the following shift in approach when developing with XMTP:
-
Instead of assuming an Ethereum address as the unique identifier, developers should default to using the
inboxIdwhere possible. -
Inbox IDs now have a list of identity objects that explicitly include the identity type (kind) and the identifier. For example:
[ PublicIdentity(kind: ETHEREUM, identifier: "0x1234567890abcdef1234567890abcdef12345678"), PublicIdentity(kind: PASSKEY, identifier: "AQIDBAUGBwgJCgsMDQ4PEBESExQVFhcYGRobHB0eHyAhIiMk"), ]
Warning
The following function changes (addresses → inboxIds) won't trigger errors since both parameters are strings. Your code will compile but may fail at runtime. Pay special attention to these changes when upgrading.
- Where you previously passed Ethereum
addresses, you must now passinboxIdsaddMembers(addresses)→addMembers(inboxIds)removeMember(addresses)→removeMembers(inboxIds)newGroup(addresses)→newGroup(inboxIds)newConversation(address)→newConversation(inboxId)
Warning
The following function changes (inboxIds → PublicIdentity objects) won't trigger errors since both parameters are strings. Your code will compile but may fail at runtime. Pay special attention to these changes when upgrading.
-
Where you previously passed
inboxIds, you must now passPublicIdentityobjectsaddMembersByInboxIds(inboxIds)→addMembersByIdentities(PublicIdentitys)removeMemberByInboxIds(inboxIds)→removeMemberByIdentities(PublicIdentitys)newGroupWithInboxIds(inboxIds)→newGroupWithIdentities(PublicIdentitys)newConversationWithInboxId(inboxId)→newConversationWithIdentity(PublicIdentity)
-
We recommend moving away from using
addressin code completely. If you MUST useaddress, anaddressmust now be wrapped in aPublicIdentityobject.So,
0x1234567890abcdef1234567890abcdef12345678must now be wrapped inPublicIdentity(ETHEREUM, “0x1234567890abcdef1234567890abcdef12345678”).For example,
newConversation("0x1234567890abcdef1234567890abcdef12345678")must now be:newConversationWithIdentity(PublicIdentity(kind: ETHEREUM, identifier: "0x1234567890abcdef1234567890abcdef12345678"))
-
We recommend that you store
inboxIdvalues alongsideaddressvalues in your User table for quick and easy lookup. -
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
inboxIdoraddress.findInboxIdFromIdentity( PublicIdentity(kind: ETHEREUM, identifier: "0x1234567890abcdef1234567890abcdef12345678"), ) findInboxStateFromInboxIds(”asdfjhaslkdfjhasldf”, “asdfjhasldff”)
inboxState: { identifiers: listOf(PublicIdentities) inboxId installations: listOf(Installation) }
val ethAddresses = identifiers.filter {it.kind == ETHEREUM }.map { it.identifier } EnsLookUp(ethAddress)
To learn more about how to work with the new inbox-based identity model, see Upgrade to XMTP V3.
Wallet and signer updates
The term “wallet” has been removed from the codebase. This is to align with future support for Passkeys and other non-wallet-based authentication methods.
This release also includes a breaking change to SigningKey, where it had a field called WalletType, which is now SignerType. SignerType provides the actual thing that signs, such as an EOA or SCW.
SigningKey now supports only one sign method: sign(signatureText: String): SignedData. It no longer supports the following sign methods:
signSCW(signatureText: String): ByteArraysign(message: String): Proto.Signaturesign(digest: ByteArray): Proto.Signature
Naming and function housekeeping
- Removed
appVersionclient option Messagerenamed toDecodedMessagefallbackContentrenamed tofallbackConversationTyperenamed toConversationFilterTypegroupremoved from names insidegroupclass.updateGroupNamerenamed toupdateNameupdateGroupNamePermissionrenamed toupdateNamePermissionupdateGroupDescriptionrenamed toupdateDescriptionupdateGroupDescriptionPermissionrenamed toupdateDescriptionPermissionupdateGroupImageUrlSquarerenamed toupdateImageUrl
imageUrlSquarerenamed toimageUrlconvoIdrenamed toconversationIdaddMembersnow returnsGroupMembershipResultwhich includesinboxIdsthat were added or removed, as well as installations that failed during the membership sync.
Recently added features
Disappearing messages
This release provides support for disappearing (ephemeral) messages. These are messages that are intended to be visible to users for only a short period of time. After the message expiration time passes, the messages are removed from the UI and deleted from local storage so the messages are no longer accessible to conversation participants.
To learn more, see Support disappearing messages with XMTP.
Multiple remote attachments
This release provides support for sending multiple remote attachments in a single message.
To learn more, see Support multiple remote attachments of any size.
Future-proofing app interoperability
This release introduces error handling that will help support app interoperability across SDK versions, even when breaking changes are required in the future.
In the future, an SDK version may introduce a breaking change, such as a feature that works only for apps on the latest versions of the SDK. Instead of forcing immediate upgrades or causing apps on older versions to break, this update adds a safety net that gracefully handles breaking changes.
At this time, no features rely on this mechanism, and no action is needed. However, this ensures your app remains resilient to future SDK updates that introduce breaking changes.
What's Changed
- Passkey Read by @nplasterer in #389
- SDK Naming and Function Cleanup by @nplasterer in #390
- Update Signer to be more universal by @nplasterer in #394
- Add paused for min version function by @cameronvoell in #396
- Add identity to client by @nplasterer in #397
- Release Candidate by @nplasterer in #395
Full Changelog: 3.0.29...4.0.0-rc1
Contributors
Assets 2
Release v3.0.29
3.0.29 (2025-03-06)
What's Changed
- Should Push for Push Notifications by @nplasterer in #392
Full Changelog: 3.0.28...3.0.29