Delivering A World-Class Developer Experience

At Immutable, we are incredibly passionate about developer experience. Developers power our protocol by creating the content, marketplaces, apps, and tools at the heart of the Immutable ecosystem — we need to ensure their experience is world-class.

Today, Immutable’s developer experience is mixed. We have powerful APIs that allow for fantastic NFT projects to be built quickly and efficiently — you can even create whole marketplaces with no backend! However, getting started on IMX can be complex and confusing:

• The IMX-SDK, which includes the frontend Link SDK (which deals with user wallet interactions) and the ImmutableXClient (the core API client), isn’t open source and is complex, strange and bloated.
• Our Documentation is often unclear, lengthy or outdated.
• Developers lack adequate functionality to understand what is happening with their NFT projects, and there’s no centralised visibility into errors, logs, insights and analytics.

Despite these challenges, our developers have already built projects and marketplaces which have processed hundreds of millions of dollars in NFT volume. However, to onboard the next 100 million traders to true ownership, we must deliver a world-class developer experience. As such, we are making a significant investment into several core DX pillars:

1. Documentation & Examples
2. SDKs
3. API Design
4. Developer Dashboard

Documentation

Our vision for Immutable’s Documentation is to build customer-centric, personalised and outcome-focused content that helps developers get things done efficiently. Today, we’re launching a huge documentation upgrade — a new home page and a new content system, both 100% open source. We’re upgrading every page of our documentation to contain better explanations, how-to guides and tutorials to cover various levels of expertise.

We’ve rebuilt this new documentation portal using Docusaurus, enabling us to support open source contributions while retaining our complex information architecture. In the spirit of web3, we’re making our documentation open-source and open for contributions from anyone, with recognition and rewards for those who contribute the most. You can view the complete source code here or read the contributors policy. Please raise issues with existing content and request new content through Github issues.

Expect to see a lot of action on our documentation over the next few months. If you’d like to help us improve here, you can either contribute directly or join us as a full-time Technical Writer!

SDKs

The Immutable SDK is the primary way developers interface with our system. Whether it’s in-game engines like Unity and Unreal, on native platforms like iOS and Android, or on the web, we want to enable any developer to integrate with Immutable X in a type-safe and straightforward manner.

The SDK is the first place most developers go when utilising our systems, and until this week, it was not up to scratch. Before launching our new IMX Core SDK, the only official SDK was the closed source javascript/typescript SDK. Additionally, this SDK does a considerable amount of work. This SDK is heavily coupled with the Link SDK and the Immutable Marketplace. There are modules in the SDK that no one outside Immutable uses, making it difficult for new developers to read and understand what our SDK is doing. Furthermore, the SDK also handles:

• Complex stark-encoding mechanics
• Helper functions directly related to link or marketplace
• IMX specific fee calculations

This complexity made it more challenging for external developers to use, but it also made it extremely difficult to auto-generate the SDK in other languages, a key component of our future strategy. Our goal was to have SDKs for 10+ languages and platforms over the course of 2022, but we knew we had nowhere near the capacity to create and maintain those SDKs unless the bulk of their codebase was auto-generated.

We took this opportunity to restructure our core SDK entirely — the components used most commonly by integrating projects. We’re incredibly excited to release the first version of the new Immutable X Core SDK. We’ve made a few significant changes:

• Removed all unnecessary code
• Converted all API calls and smart contract calls to be auto-generated
• Split out the Link SDK into a different product. We’ll be releasing an article detailing our upgraded Wallet SDK soon. For now, you can still use the original IMX SDK for all Link-related actions, and this new SDK for actions which don’t require the Link.
• Massively reduced the number of dependencies and the overall size of the package.

The total number of non-generated lines of code in the SDK has been slashed by two orders of magnitude! To make this happen, we had to significantly reduce the amount of work done on the client by moving logic to the backend. For instance, you’ll notice that an additional field, `payload`, has been added to all signable endpoints. This is because we are now encoding that data on the server-side to strip out logic from the client-side SDK.

Workflow Functions

Workflows provide users with an out of the box solution for more complex operations that require multiple steps. For example, the withdrawal of an NFT requires the following steps:

• Checking if the token is mintable on L1 (for an asset minted directly to L2)
• Retrieving encoded asset details
• Checking if the user is registered on-chain
• Executing the correct contract call depending on whether the token is mintable and the user is registered

The Core SDK combines these steps into a simple workflow function that performs API requests and contract transactions. Using the building blocks provided by the Core SDK, you can recreate these workflows for customised implementations. You can view workflows in their entirety to understand what is happening under the hood. See the full code for completing an ERC721 withdrawal.

When creating SDKs in other languages, these workflows will need to be translated into the respective languages, but the incremental work required to support each new language is substantially reduced.

We plan to scale out the number of supported languages and platforms as fast as possible. We’re looking for community and developer partners to help us on this journey! Please reach out to opensource@immutable.com or create an issue on any IMX repository if you’d like to be involved in creating a v2 SDK for a particular language or platform. We’d love to have you on board.

Expect to see a lot of action on our SDKs over the next few months. If you’d like to help us improve here, you can either contribute directly or join us as a full-time Software Engineer!

API Design

At Immutable, we have an API-first approach to building our product. These APIs abstract a ton of complexity and enable developers to be more productive and faster. We also strive to make sure all our API endpoints are self-serve and permissionless.

Our APIs have been consistently performant and reliable. However, they haven’t always been fit for purpose for specific use cases, particularly for those seeking to maintain rollup or order book state independently. Various marketplaces and utility tool makers have expressed the difficulty in polling our public APIs to sync blockchain state and how inefficient the process is. There are a few examples of this:

• We don’t expose an endpoint that enables developers to get a transaction by its ID.
• To get all actions on Immutable X (as a block explorer like Immutascan might desire), you’d have to poll five endpoints (v1/mints, v1/transfers, v1/deposits, v1/withdrawals, v1/trades) using timestamp as a filter and then normalise this information into a format that enables per transaction querying.
• We don’t support event streaming, websockets, webhooks or any pattern but polling to synchronise state.

We are currently hard at work exploring new endpoints, endpoint modifications and new architecture patterns to help solve these issues — help is on the way! Good API design also involves well documented and consistent responses with clear error messages, so we’re investing in a thorough review of our error messages and publishing a detailed list of all error messages returned by our APIs.

We would love your help — if you think an endpoint is poorly designed or is returning errors that aren’t helpful, please raise a Github issue on the imx-core-sdk repository.

You can also programmatically check our API schema source of truth using our OpenAPI endpoint.

Developer Dashboard

Our team has focused its initial efforts on getting developers started. However, managing a project once deployed is also a demanding experience. We have received feedback that it can often be hard to control elements that make up a project, such as collections, API keys and minting performance. Many of these workflows involve reaching out to Immutable and asking for help. Furthermore, Immutable has nowhere to communicate with a developer outside of API responses, so we can’t provide contextual feedback to help people in their journey. All of these factors lead to a complex configuration and post-deployment process.

Our team has decided that the next piece of our developer experience suite will be a developer dashboard where developers can get information about their project performance and registration information. This dashboard will initially solve the key problems projects currently experience:

1. API Key management
2. Project and Collection Registration
3. Metadata Recrawling

In the future, we will introduce analytics into this dashboard so that developers can have a single view of how their project is performing and how users are interacting with their NFTs. We will be introducing more information about the developer dashboard in the coming months and would love feedback from our developer community — what do you want to see?

Conclusion

Currently, web3 game development is substantially more challenging than web2 game development. This is partially due to the fundamental technical challenges of this new space (which Immutable is focused on solving) but is also a product of the limited developer experience offered by web3 platforms.

We know we have to make significant investments to improve the developer experience for web3 games and marketplaces. We are building the foundation for a world-class developer experience with excellent docs, robust SDKs, data-rich APIs, and insightful dashboards with these releases.

Most importantly, we need your help. We can only build a fantastic web3 developer experience in partnership with our community. Whether you’re contributing to Docs or SDK or simply providing feedback on what you would like to see on a developer dashboard — everything is a step in the right direction. Better still, we’d love to have all engineers with developer experience or SDK experience come and join the team!

‍