How to Rotate an Inbox ID with XMTP JS SDK?

Engineering updates
1

I’m working with the XMTP JS SDK and need to understand how to rotate an inbox ID when approaching or reaching the 256 inbox updates limit.

According to the [documentation on managing inboxes](Manage XMTP inboxes, identities, and installations – Build with XMTP), the docs state:

When you create an inbox ID, a cryptographic nonce is used to create the ID. If an inbox reaches its inbox updates limit, you can increment the nonce to create a new inbox ID associated with the same wallet address.

However, I cannot find the actual implementation details or method calls for performing this rotation in the JS SDK (browser or node).

What I’ve Checked

  • The documentation explains the concept and warns about permanent loss of conversation history
  • I’ve reviewed the inbox management section but found no code examples for rotation
  • The SDK docs show methods for revoking installations and managing identities, but not inbox rotation

What I Need

Could someone provide:

  1. The specific method/function to call for rotating an inbox ID in the JS SDK?
  2. Code example showing how to increment the nonce and create the new inbox ID?
  3. Any best practices or considerations when implementing this functionality?
2 Likes
2

the browser and node SDKs have a test for this process. it doesn’t use the nonce option, but the result is the same.

browser SDK: xmtp-js/sdks/browser-sdk/test/Client.test.ts at 1eabe06fcd79ff88c29d4d97db23d64458a1a83d · xmtp/xmtp-js · GitHub
node SDK: xmtp-js/sdks/node-sdk/test/Client.test.ts at 1eabe06fcd79ff88c29d4d97db23d64458a1a83d · xmtp/xmtp-js · GitHub

3 Likes
3

Thanks for pointing me to those tests! The implementation for rotation makes sense now.

However, I have a follow-up regarding the logic for when to trigger this. Since rotating the Inbox ID creates a new identity and starts a fresh message history, I only want to do it when absolutely necessary (i.e., when the 256-update limit is reached).

  1. Error Handling: What specific error (code or message) does the JS SDK throw when an action (like adding a new installation or linking a wallet) fails because the inbox update limit has been reached?
  2. Pre-emptive Checking: Is there a way to query the current “update count” for a specific inboxId before attempting an operation?
  3. Best Practices: Is it recommended to wait for the SDK to throw a “limit reached” error and then prompt the user to rotate, or should apps be proactively monitoring this count to warn users?

I want to avoid a situation where I increment the nonce unnecessarily and cause a user to lose their conversation history.

Thank you once again.

2 Likes