Upgrading from 3Box to Ceramic and IDX

3Box Labs is sunsetting 3Box products in favor of the new and more powerful combination of Ceramic Network and IDX. In this post we provide a timeline and various upgrade paths for projects currently using 3Box.

To learn more about Ceramic, IDX, and the reasons behind the transition, read our previous post:

Timeline

Ceramic and IDX are currently live on the Clay Testnet, but since it's a testnet they're not yet suitable for production deployments. In the next month or two, we will open a soft launch of the Ceramic mainnet to select partners that require more immediate production deployments. This would include current 3Box integrations. Some time after that, mainnet will be opened to the general public.

We encourage all 3Box developers to begin their setting up and testing their migrations to Ceramic and IDX on the Clay testnet as soon as possible, and reach out to us on the Ceramic Discord if you would like your project to be included in the mainnet soft launch.

Starting today we will begin formally deprecating 3Box products, but we won't immediately turn them off. Some reasonable amount of time after Ceramic mainnet is opened to the general public, we will disconnect the 3Box servers to complete the transition. Your application will need to be migrated to Ceramic and IDX by that date (TBA) or risk losing access to current 3Box data.

Upgrade paths by 3Box product

Profiles API

All 40,000+ 3Box profiles will be migrated to IDX. Standard 3Box profile data will now be stored in three different IDX records. Basic profile fields such as those available in the 3Box Profiles app (name, image, background, emoji, etc.) will be stored in a basicProfile record. Social verifications (twitter, github) will be stored in an aka record. Links to blockchain accounts will be stored in a cryptoAccounts record.

If your application is only reading data from the 3Box profiles API, your migration is very simple. The existing 3Box profiles API will continue to work for both legacy profiles stored on 3Box and also for new and/or migrated profiles stored on IDX with no change needed. Eventually though, you will want to upgrade to js-idx and use the idx.get() method for reading basic profiles, social verifications, and crypto account links stored on IDX. This pattern will be mandatory once we disable the 3Box API service.

The migration of the three profile data sets mentioned above will automatically occur behind the scenes the first time a user logs in to any application that uses 3ID Connect. For this reason, we recommend adding 3ID Connect to your sign-in flow even if you do not need to write data to IDX. This will ensure that the profiles for all of your users are migrated during the migration window.

If your application is setting or modifying standard data in a user profile, then you should upgrade from 3box-js to js-idx and use the idx.set() method to write to any of the profile data sets mentioned above.

If your application is storing custom, non-standard data in a user profile or if you created an app-specific profile in a 3Box Space, you will need to manually perform a migration for this data set. First, you need to create a custom definition for your data set. Then, the next time a given user logs in to your site (ideally using 3ID Connect so their standard profile data gets automatically migrated), you need to query their profile from the 3Box API, extract your custom data from their profile, then store this data in an IDX record using idx.set().

Profiles App

The 3Box Profiles app, which provides a simple UI for creating and managing profiles, will eventually be replaced by Self.ID built on Ceramic and IDX. In the meantime, 3Box Hub can continue to be used since all data will be migrated to IDX. Once Self.ID is live on Ceramic mainnet and using 3ID Connect for authentication, we will launch a marketing campaign to get users to sign in which will migrate their standard profiles to IDX.

Spaces and Threads APIs

Projects using 3Box spaces and threads APIs for storage and messaging will now need to replicate this functionality in their application using a combination of IDX for identity and either Ceramic documents or other datastores (such as Textile, OrbitDB, SkyDB, etc.) for content storage.

If you are storing simple JSON content in your space, then we recommend creating a custom definition for your data model, and using the idx.set() and idx.get() methods for interacting with it. For migrating existing data, you should query the data using the 3Box spaces API, then write it to an IDX record after the user has authenticated.

If you are storing large volumes of data in a space, have high transaction throughput, require encryption, or are using messaging, then there are many nuances and directions your integration could take depending on your specific use case. We'd recommend joining the Ceramic Discord for assistance with your migration.

Plugins

3Box UI plugins including Comments, Chatbox, and Profile Hover will be deprecated without replacement. We understand this is less than optimal for existing projects, but we as a team have limited capacity to continue maintaining these with a high bar for quality. Since these components are just a thin UI, these functionalities can easily be replicated by adding IDX and Ceramic to your project and coding some simple HTML/CSS.

Hosting

3Box Labs has provided free hosting and persistence for data stored in 3Box. Moving forward, things will be a bit different due to the decentralized nature of Ceramic.

For historical 3Box data, 3Box Labs will continue to host and persist this content until some reasonable amount of time (TBA) after Ceramic mainnet has launched. This gives you a chance to upgrade your application and replicate the data of your users to Ceramic and IDX. After the migration window is over, we will be turning off our 3Box servers.

For new data stored in Ceramic and IDX, 3Box Labs will offer a few free hosted node options:

• 3Box Labs node: A full Ceramic node that persists the profile data of users who automatically perform their profile migration via 3ID Connect (from any app) and users who manage their profile data in the Self.ID app.
• Community gateway: A read-only Ceramic node.
• Community dev node: A full Ceramic node used for prototyping and development, but does not guarantee data persistence. It will be wiped from time to time beginning at mainnet launch.
• The endpoints for the gateway and dev node can be found in the Ceramic and IDX docs.

If you are building a production application and need to persist data on Ceramic and IDX, it is recommended that you either run your own Ceramic node or utilize a third-party node hosting service for persisting your data. We are engaging with various hosting providers to offer Ceramic nodes, and we expect these to be available over time.

What to expect from 3Box products during this transition

We are quickly working towards a mainnet release of Ceramic so you can begin to utilize this new powerful infrastructure as soon as possible. However it is likely that you may experience various issues with existing 3Box services in the meantime, such as slowness, loading, syncing issues, or log-in/browser compatibility. We deeply apologize for these inconveniences. The reality is many of these issues are out of our control and are caused from underlying technology dependencies. Normally, we would be working to fix these as soon as possible, but in this case the most impactful thing we can do is ship Ceramic mainnet faster. These are some of the reasons we're excited to move to this new Ceramic-based architecture.

Questions or support?

We're always available to answer any questions and help you through this transition. Reach out to us in the Ceramic Discord for assistance.