4.0.0-rc1

xmtp-ios v4.0.0-rc1

This release focused on delivering an SDK for a stable, performant, and hardened XMTP V3.

Important

Please upgrade your app to use xmtp-ios ≥v4.0.0 by May 1, 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 inboxId where 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 pass inboxIds
  • addMembers(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 pass PublicIdentity objects

  • addMembersByInboxIds(inboxIds) → addMembersByIdentities(PublicIdentitys)
  • removeMemberByInboxIds(inboxIds) → removeMemberByIdentities(PublicIdentitys)
  • newGroupWithInboxIds(inboxIds) → newGroupWithIdentities(PublicIdentitys)
  • newConversationWithInboxId(inboxId) → newConversationWithIdentity(PublicIdentity)

• We recommend moving away from using address in code completely. If you MUST use address, an address must now be wrapped in a PublicIdentity object.

  So, 0x1234567890abcdef1234567890abcdef12345678 must now be wrapped in PublicIdentity(.ethereum, “0x1234567890abcdef1234567890abcdef12345678”).

  For example, newConversation("0x1234567890abcdef1234567890abcdef12345678") must now be:

  newConversationWithIdentity(PublicIdentity(kind: .ethereum, identifier: "0x1234567890abcdef1234567890abcdef12345678")) 

• We recommend that you store inboxId values alongside address values 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 inboxId or address.

  findInboxIdFromIdentity(  PublicIdentity(kind: .ethereum, identifier: "0x1234567890abcdef1234567890abcdef12345678"),
  )
  findInboxStateFromInboxIds(”abcdefghijklmnopxrstuvwqyz”, “abcdefghijklmnopxrstuvwqyz”)

  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): ByteArray
• sign(message: String): Proto.Signature
• sign(digest: ByteArray): Proto.Signature

Naming and function housekeeping

• Removed appVersion client option
• Message renamed to DecodedMessage
• fallbackContent renamed to fallback
• ConversationType renamed to ConversationFilterType
• group removed from names inside group class.
  • updateGroupName renamed to updateName
  • updateGroupNamePermission renamed to updateNamePermission
  • updateGroupDescription renamed to updateDescription
  • updateGroupDescriptionPermission renamed to updateDescriptionPermission
  • updateGroupImageUrlSquare renamed to updateImageUrl
• imageUrlSquare renamed to imageUrl
• convoId renamed to conversationId
• addMembers now returns GroupMembershipResult which includes inboxIds that 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 #476
• SDK Naming and Function Cleanup by @nplasterer in #477
• Update Signer to be more universal by @nplasterer in #479
• Add paused for min version function by @cameronvoell in #480
• Add identity to client by @nplasterer in #481
• Small test fix by @nplasterer in #482

Full Changelog: 3.0.30...4.0.0-rc1

3.0.29

What's Changed

• Disappearing messages by @nplasterer in #466
• Fix Bad Key Packages by @nplasterer in #470
• Added multi remote attachment codec and test by @cameronvoell in #469

Full Changelog: 3.0.28...3.0.29

3.0.27

What's Changed

• Revert "remove client from serializable objects" by @nplasterer in #463
• Remove pinned frame url by @nplasterer in #464

Full Changelog: 3.0.26...3.0.27

3.0.26

What's Changed

• fix visibility of new childMessagesProperty by @cameronvoell in #462

Full Changelog: 3.0.25...3.0.26

3.0.25

What's Changed

• dm validation fix; upstream changes by @cameronvoell in #461

Full Changelog: 3.0.24...3.0.25

3.0.24

What's Changed

• Consent filtering by array by @nplasterer in #460

Full Changelog: 3.0.23...3.0.24

3.0.18

What's Changed

• Sync All Conversations Consent Filtering by @nplasterer in #449

Full Changelog: 3.0.17...3.0.18

3.0.17

What's Changed

• Update libxmtp ref for fork fix by @cameronvoell in #448

Full Changelog: 3.0.16...3.0.17

3.0.15

What's Changed

• Fix send encoded content in Conversation class by @cameronvoell in #446

Full Changelog: 3.0.14...3.0.15

3.0.12

What's Changed

• Sync all syncs all by @nplasterer in #441

Full Changelog: 3.0.11...3.0.12