4.0.0-rc2

xmtp-react-native 4.0.0-rc2

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

Important

Please upgrade your app to use xmtp-react-native ≥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-react-native ≥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)(https://docs.xmtp.org/inboxes/build-inbox#create-an-account-signer), 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(”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): ByteArray. 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 #617
• Release candidate by @nplasterer in #618

Full Changelog: v3.1.17...4.0.0-rc1

• Signature update by @nplasterer in #619
• Release Candidate 2 by @nplasterer in #620

Full Changelog: 4.0.0-rc1...4.0.0-rc2

v3.1.17

Patch Changes

• e0e92b3: - adds should_push to messages for push notifications handling
  • fixes occasional rust panic crash in streams

3.1.13

Android: 3.0.26
iOS: 3.0.30

What's Changed

• Revert client removal by @nplasterer in #593
• release: version packages by @github-actions in #594
• Messages with reactions function, dm fix by @cameronvoell in #596
• Remove pinned frame url by @nplasterer in #597
• release: version packages by @github-actions in #598
• Update bindings by @nplasterer in #599
• release: version packages by @github-actions in #600
• Multi attachment content type by @cameronvoell in #602
• Disappearing Messages by @nplasterer in #603
• release: version packages by @github-actions in #604

Full Changelog: 3.1.10...3.1.13

3.1.10

What's Changed

• fix: Read Receipt Decoded Value by @alexrisch in #562
• Add custom content types for preparing a message by @nplasterer in #568
• Fork fixes via intent filter fix by @cameronvoell in #569
• update node versions by @cameronvoell in #570
• release: version packages by @github-actions in #571
• Sync All Conversations Consent Filtering by @nplasterer in #573
• Rename senderAddress to senderInboxId by @nplasterer in #574
• Speed up build client performance by @nplasterer in #575
• release: version packages by @github-actions in #576
• Re-Enable History Sync by @nplasterer in #578
• release: version packages by @github-actions in #580
• V3 HMAC key support for self push notifications by @nplasterer in #582
• release: version packages by @github-actions in #584
• Remove client from serializable objects & Revoke installations by @nplasterer in #586
• release: version packages by @github-actions in #587
• Consent filtering by array by @cameronvoell in #589
• release: version packages by @github-actions in #590
• fixes exportNativeLogs on iOS by @cameronvoell in #591
• release: version packages by @github-actions in #592

Full Changelog: v3.1.2...3.1.10

v3.1.2

What's Changed

• Add Changesets and remove semantic releases by @nplasterer in #556
• Example app fixes by @cameronvoell in #557
• Fixes remote attachments testing in example app by @cameronvoell in #558
• Add back custom content type ability. by @nplasterer in #559
• set node to 20 and fix release action by @cameronvoell in #564
• release: version packages by @github-actions in #565

Full Changelog: v3.1.1...v3.1.2

v3.1.1

3.1.1 (2024-12-05)

Bug Fixes

• up the performance test (dedd2fe)

v3.1.0

3.1.0 (2024-12-03)

Features

• Decoded Message Types (31af769)

v3.0.8

3.0.8 (2024-11-26)

Bug Fixes

• add consent streaming (f0eb4a7)

v3.0.7

3.0.7 (2024-11-22)

Bug Fixes

• do the iOS side (c881f71)

v3.0.6

3.0.6 (2024-11-20)

Bug Fixes

• processMessage: await processMessage and handle object (64ffe9d)