Domain Migrations for Mini Apps

[CassOnMars]

The current version of the manifest specification for Mini Apps is a strict 1:1 mapping to domains, which can be challenging for developers who need to migrate, as:

• The new domain would need to be re-added, losing all notification preferences
• The developer metrics would be disconnected from old and new
• The old mini app domain would need to be turned into a notice page so that users know to add the new one

There are a few different changes that would be helpful for these scenarios, but the first of them, which can be progressively improved, is a simple addition:

Change: Add a new field to the frame body, canonicalDomain

**Served from example.xyz:**
{
  "accountAssociation": {
    "header": "eyJma...In0",
    "payload": "eyJkb...bSJ9",
    "signature": "MHg...MzFj"
  },
  "frame": {
    "version": "1",
    "name": "Example Mini App",
    "iconUrl": "https://example.xyz/icon.png",
    "homeUrl": "https://example.xyz",
    "imageUrl": "https://example.xyz/image.png",
    "buttonTitle": "Check this out",
    "splashImageUrl": "https://example.xyz/splash.png",
    "splashBackgroundColor": "#eeccff",
    "webhookUrl": "https://example.xyz/api/webhook",
    **"canonicalDomain": "example.xyz"**
  }
}

**Served from example.com:**
{
  "accountAssociation": {
    "header": "eyJma...In0",
    "payload": "eyJkb...bSJ9",
    "signature": "MHg...MzFj"
  },
  "frame": {
    "version": "1",
    "name": "Example Mini App",
    "iconUrl": "https://example.com/icon.png",
    "homeUrl": "https://example.com",
    "imageUrl": "https://example.com/image.png",
    "buttonTitle": "Check this out",
    "splashImageUrl": "https://example.com/splash.png",
    "splashBackgroundColor": "#eeccff",
    "webhookUrl": "https://example.com/api/webhook",
    **"canonicalDomain": "example.xyz"**
  }
}

Developers
canonicalDomain will decide which domain is the primary domain to be served to users for mini apps and notifications. If omitted, the domain from the accountAssociation remains the primary domain. If canonicalDomain is used, both the domain in the accountAssociation and the canonicalDomain must have a manifest, signed by the same FID, to successfully apply the mapping.

Farcaster Client
The client will use the canonical domain value to replace the domain of the given urls, if necessary. Any notifications originally linking to the prior domain should now link to the new domain for the mini app.

Adoption
This is a non-breaking change. If a Farcaster client implementation does not support it, the previous domains should still work for as long as the domain continues to serve the manifest.

[mcilroyc]

I like the idea of solving this problem. But it seems like this is a partial solution that might just be adding complexity. Isn't a long term solution to give mini apps their own FID and then tie notifications, etc., to that stable value?

[CassOnMars]

Per-app FIDs was a consideration, but there's some drawbacks to that approach:

No decrease in complexity overall
Instead of having to manage an account for a publisher, creators would now have to manage multiple accounts and signers. While some mini apps are created by teams with only one or two mini apps, there are prolific creators that have made dozens. This effectively shifts the complexity from Farcaster client implementations to the mini app developers themselves.

Increased cost to developers
With the FID per mini app approach, developers would have to pay for the cost of an account and storage, instead of the much smaller per-byte cost of serving a manifest.

No backwards compatibility
If mini apps were 1:1 with FIDs, the previously mentioned prolific creators would not only be required to migrate to these new accounts, but Farcaster client implementations would also still be required to handle the breaking change.

In comparison, adding support for a one line addition to a manifest and a modest amount of data ingestion and request processing on the client implementation side had a lower impact calculus.

[mattleesounds]

This would really help me out! Thank you @CassOnMars. I have been wanting to change my mini app's domain for a month and haven't been able to.

[nyusternie]

@CassOnMars
How does the domain migration work with sub-domains, e.g. app.example.xyz, migrating to app.example.com?

In my case, my webhook URL is also a sub-domain, e.g. webhook.example.xyz would have to map to webhook.example.com. Does the current proposal support migration/mapping for sub-domain'd mini apps as well?

If so, I'm assuming the new canonicalDomain will have to be set to the hostname (i.e. example.com), for all the "subs" to migrate & work as expected?

Thanks!