@xmtp/content-type-remote-attachment@2.0.1

Patch Changes

• Updated dependencies [340fcf4]
  • @xmtp/content-type-primitives@2.0.1
  • @xmtp/proto@3.78.0
  • @noble/secp256k1@2.2.3

@xmtp/content-type-read-receipt@2.0.1

Patch Changes

• Updated dependencies [340fcf4]
  • @xmtp/content-type-primitives@2.0.1

@xmtp/content-type-reaction@2.0.1

Patch Changes

• Updated dependencies [340fcf4]
  • @xmtp/content-type-primitives@2.0.1

@xmtp/content-type-primitives@2.0.1

Patch Changes

• 340fcf4: Upgraded @xmtp/proto dependency

@xmtp/content-type-group-updated@2.0.1

Patch Changes

• Updated dependencies [340fcf4]
  • @xmtp/content-type-primitives@2.0.1
  • @xmtp/proto@3.78.0

@xmtp/browser-sdk@1.1.1

Patch Changes

• Updated dependencies [340fcf4]
  • @xmtp/content-type-group-updated@2.0.1
  • @xmtp/content-type-primitives@2.0.1
  • @xmtp/content-type-text@2.0.1
  • @xmtp/proto@3.78.0
  • uuid@11.1.0

@xmtp/node-sdk@1.0.1

Patch Changes

• 607ae92: Fixed IdentifierKind enum export in build

@xmtp/browser-sdk@1.1.0

Minor Changes

• 999bb78: Added inboxStateFromInboxIds to Preferences

@xmtp/node-sdk@1.0.0

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

Important

Please upgrade your app to use @xmtp/node-sdk ≥ 1.0.0 by May 1, 2025 to continue using XMTP. On May 1, XMTP V3 will enforce this minimum SDK version. Apps on outdated V3 SDKs will lose connectivity.

Upgrade from 0.0.x to 1.0.0

Use the information in these release notes to upgrade from @xmtp/node-sdk 0.0.x to 1.0.0.

Important

Upgrading from a legacy XMTP V2 SDK? Legacy XMTP V2 SDKs include JavaScript SDK vx.x.x. To learn how to upgrade to stable XMTP V3, be sure to also see important dates and considerations in Upgrade from a legacy XMTP V2 SDK.

Breaking changes

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 an inbox ID where possible.

• Where you previously used an Ethereum address, you must now use an inbox ID

  • addMembers(addresses) → addMembers(inboxIds)
  • removeMember(addresses) → removeMembers(inboxIds)
  • newGroup(addresses) → newGroup(inboxIds)
  • newDm(address) → newDm(inboxId)

Warning

These function changes (address → inbox ID) won't trigger errors since both parameters are strings. Your code will pass a type-check but may fail at runtime. Pay special attention to these changes when upgrading.

• The previous methods that allowed the use of an inbox ID have been removed in favor of the above methods

  • addMembersByInboxIds(inboxIds)
  • removeMembersByInboxIds(inboxIds)
  • newGroupByInboxIds(inboxIds)
  • newDmByInboxId(inboxId)

• New methods have been added to allow the use of addresses with the Identifier type

  • addMembersByIdentifiers(Identifier[])
  • removeMembersByIdentifiers(Identifier[])
  • newGroupByIdentifiers(Identifier[])
  • newDmByIdentifier(Identifier)

• We recommend moving away from using addresses in code completely. However, if you MUST use addresses, wrap them with the Identifier type.

  For example, the address 0x1234567890abcdef1234567890abcdef12345678 must now be wrapped like so:

  const identifier: Identifier = {
    identifier: "0x1234567890abcdef1234567890abcdef12345678",
    identifierKind: IdentifierKind.Ethereum,
  };

• 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 inbox ID or address.

  // get an inbox ID from an address
  const inboxId = await getInboxIdForIdentifier({
    identifier: "0x1234567890abcdef1234567890abcdef12345678",
    identifierKind: IdentifierKind.Ethereum,
  });
  
  // find the addresses associated with an inbox ID
  const inboxState = await client.inboxStateFromInboxIds([inboxId]);
  
  interface InboxState {
    inboxId: string
    recoveryIdentifier: Identifier
    installations: Installation[]
    identifiers: Identifier[]
  }
    
  const addresses = inboxState.identifiers
    .filter((i) => i.identifierKind === IdentifierKind.Ethereum)
    .map((i) => i.identifier);

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 includes breaking changes to the Signer type.

• The walletType field is now type. The type field refers to the type of account that will sign messages, such as an EOA or SCW.
• The getAddress field has been replaced by getIdentifier, which is a function that returns an Identifier type.

// old
const address = await signer.getAddress();

// new
const identifier = await signer.getIdentifier();
// identifier may not be an Ethereum address
const address = identifier.identifierKind === IdentifierKind.Ethereum ?
  identifier.identifier :
  undefined;

Consent and inbox state have been moved to client.preferences

Everything related to consent, inbox state, and user preferences is now part of the Preferences class and accessible via client.preferences.

• client.inboxState → client.preferences.inboxState
• client.getLatestInboxState → client.preferences.getLatestInboxState
• client.inboxStateFromInboxIds → client.preferences.inboxStateFromInboxIds
• client.getConsentState → client.preferences.getConsentState
• client.setConsentStates → client.preferences.setConsentStates
• client.conversations.streamConsent → client.preferences.streamConsent
• client.conversations.streamPreferences → client.preferences.streamPreferences

Other recent changes

Conversations are now instances of Group or Dm

The new Group and Dm classes extend the Conversation class and provide specific functionality based on the conversation type.

Note

client.conversations.list() now returns an array of Group or Dm classes. When accessing specific functionality based on conversation type, you must check the type first so that the TypeScript compiler can narrow the type.

const conversations: (Group | Dm)[] = await client.conversations.list();

for (const conversation of conversations) {
  // narrow the type to Group to access the group name
  if (conversation instanceof Group) {
    console.log(group.name);
  }

  // narrow the type to Dm to access the peer inboxId
  if (conversation instanceof Dm) {
    console.log(conversation.peerInboxId);
  }
}

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.

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.

@xmtp/browser-sdk@1.0.0

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

Important

Please upgrade your app to use @xmtp/browser-sdk ≥ 1.0.0 by May 1, 2025 to continue using XMTP. On May 1, XMTP V3 will enforce this minimum SDK version. Apps on outdated V3 SDKs will lose connectivity.

Upgrade from 0.0.x to 1.0.0

Use the information in these release notes to upgrade from @xmtp/browser-sdk 0.0.x to 1.0.0.

Important

Upgrading from a legacy XMTP V2 SDK? Legacy XMTP V2 SDKs include JavaScript SDK vx.x.x. To learn how to upgrade to stable XMTP V3, be sure to also see important dates and considerations in Upgrade from a legacy XMTP V2 SDK.

Breaking changes

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 an inbox ID where possible.

• Where you previously used an Ethereum address, you must now use an inbox ID

  • addMembers(addresses) → addMembers(inboxIds)
  • removeMember(addresses) → removeMembers(inboxIds)
  • newGroup(addresses) → newGroup(inboxIds)
  • newDm(address) → newDm(inboxId)

Warning

These function changes (address → inbox ID) won't trigger errors since both parameters are strings. Your code will pass a type-check but may fail at runtime. Pay special attention to these changes when upgrading.

• The previous methods that allowed the use of an inbox ID have been removed in favor of the above methods

  • addMembersByInboxIds(inboxIds)
  • removeMembersByInboxIds(inboxIds)
  • newGroupByInboxIds(inboxIds)
  • newDmByInboxId(inboxId)

• New methods have been added to allow the use of addresses with the Identifier type

  • addMembersByIdentifiers(Identifier[])
  • removeMembersByIdentifiers(Identifier[])
  • newGroupByIdentifiers(Identifier[])
  • newDmByIdentifier(Identifier)

• We recommend moving away from using addresses in code completely. However, if you MUST use addresses, wrap them with the Identifier type.

  For example, the address 0x1234567890abcdef1234567890abcdef12345678 must now be wrapped like so:

  const identifier: Identifier = {
    identifier: "0x1234567890abcdef1234567890abcdef12345678",
    identifierKind: "Ethereum",
  };

• 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 inbox ID or address.

  // get an inbox ID from an address
  const inboxId = await getInboxIdForIdentifier({
    identifier: "0x1234567890abcdef1234567890abcdef12345678",
    identifierKind: "Ethereum",
  });
  
  // find the addresses associated with an inbox ID
  const inboxState = await client.inboxStateFromInboxIds([inboxId]);
  
  interface InboxState {
    inboxId: string
    recoveryIdentifier: Identifier
    installations: Installation[]
    identifiers: Identifier[]
  }
    
  const addresses = inboxState.identifiers
    .filter((i) => i.identifierKind === "Ethereum")
    .map((i) => i.identifier);

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 includes breaking changes to the Signer type.

• The walletType field is now type. The type field refers to the type of account that will sign messages, such as an EOA or SCW.
• The getAddress field has been replaced by getIdentifier, which is a function that returns an Identifier type.

// old
const address = await signer.getAddress();

// new
const identifier = await signer.getIdentifier();
// identifier may not be an Ethereum address
const address = identifier.identifierKind === "Ethereum" ?
  identifier.identifier :
  undefined;

Consent and inbox state have been moved to client.preferences

Everything related to consent, inbox state, and user preferences is now part of the Preferences class and accessible via client.preferences.

• client.inboxState → client.preferences.inboxState
• client.getLatestInboxState → client.preferences.getLatestInboxState
• client.inboxStateFromInboxIds → client.preferences.inboxStateFromInboxIds
• client.getConsentState → client.preferences.getConsentState
• client.setConsentStates → client.preferences.setConsentStates
• client.conversations.streamConsent → client.preferences.streamConsent
• client.conversations.streamPreferences → client.preferences.streamPreferences

Other recent changes

Conversations are now instances of Group or Dm

The new Group and Dm classes extend the Conversation class and provide specific functionality based on the conversation type.

Note

client.conversations.list() now returns an array of Group or Dm classes. When accessing specific functionality based on conversation type, you must check the type first so that the TypeScript compiler can narrow the type.

const conversations: (Group | Dm)[] = await client.conversations.list();

for (const conversation of conversations) {
  // narrow the type to Group to access the group name
  if (conversation instanceof Group) {
    console.log(group.name);
  }

  // narrow the type to Dm to access the peer inboxId
  if (conversation instanceof Dm) {
    console.log(conversation.peerInboxId);
  }
}

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.

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.