For Developers Only: This technical migration guide is your companion through the transition to Lens V2. Users, rest assured, there's no action needed on your part to enjoy Lens V2.

We are nearing October 30, the Lens V2 mainnet migration date. This is a significant milestone in our journey towards the next-generation, decentralized social web. The entire Lens V2 codebase has been rewritten, refactored and optimized, paving the way for a more open, composable and developer-friendly ecosystem. Migrating to the Lens API V2 alone means you are going to get at least 2x the speed and a more scalable system.

Plan of action

1. Testnet - (no later than 5 hours before mainnet) we will be simulating the upgrades on forks in our own testnet environment. The sandbox testnet will not be upgraded and eventually will be decommissioned. The V2 upgrade no longer requires modules to be whitelisted by our team.

2. October 27th, 21:00 UTC - Lens API V2 will be deployed before the migration starts. Please note this will have V1 data in V2 form but not have any following records as it will be in the legacy table and data will not be exposed.

   1. We will expose a method called LensProtocolVersion, which will allow you to poll to see when the upgrade has taken place if you wish to apply your migration and switch automatically. https://docs.lens.xyz/V2/docs/get-lens-protocol-version - when this return “2.0.0” you know its upgraded

   2. Mumbai API URL - https://api-V2-mumbai.lens.dev

   3. Polygon API URL - https://api-V2.lens.dev

   4. If you have a native app that has to go through a review we recommend mapping this in a config file or switch based on the above states.

3. October 30th, 15:00 UTC - V2 Migration starts

   From this time forward, the Lens API V1 will stop accepting writes and go into read-only mode. It will continue to return old data and will be alive for only 3 months thereafter on January 30, 2024.

4. October 30th, 15:10 UTC - Upgrade Protocol to V2

   1. To be safe during the data migration on the API, please pause the following activities. Note: We added “Legacy” to the names to identify as V1 modules. Contract names do not start with “Legacy.”

   2. Any publications with LegacyDegreeOfSeparationReferenceModule and LegacyFollowerOnlyReferenceModule will not be able to be commented on or mirrored after the upgrade.

   3. Any publications that had followers only will not be collectible after the upgrade

      • i. LegacySimpleCollectModule with followerOnly = true

        ii. LegacyFeeCollect with followerOnly = true

        iii. LegacyLimitedFeeCollect with followerOnly = true

        iv. LegacyFreeCollect with followerOnly = true

        v. LegacyLimitedTimedFeeCollect with followerOnly = true

        vi. LegacyMultiRecipientFeeCollect with followerOnly = true

        vii. LegacyTimedFeeCollect with followerOnly = true

5. October 30th, 15:30 UTC - Run API migration scripts (approx. 1-2 hours)

   • Bring any API-only data across to V2 API

   • Apply follow-state, handle state and profile state

   • The V2 API will have all of the V1 data migrated and fetchable, but only in the V2 form table structures. For example, any endpoints you call, getting comments of a publication, will still bring back V1 comments; it is all backwards compatible on the read side.

6. October 30th, 16:30-17:30 UTC - Unpause Follows on the protocol

7. October 30th, 16:30-17:30 UTC - Lens API V2 is ready and working - apps will work as normal, and if using the Lens API the data will be fully migrated

8. October 30th, 16:30-17:30 UTC - Complete upgrade

Background processing

With the significant changes made to Lens V2, we need to migrate the data onchain. This involves around 20 million transactions, which will be handled behind the scenes. The order of migration is determined by user activity and other factors, rather than the profile ID sequence, ensuring that active and genuine users are prioritized.

1. October 30th, 16:30-17:30 UTC - Migration detach profiles from handles (approx. 3-4 hours)

Events:

Profile migrated event - event emitted from LensHub

event ProfileMigrated(
  uint256 profileId
);

The handle gets minted to the owner of the profile - event emitted from LensHandlesProxy

event HandleMinted(
   string handle, // this will be just the name aka wagmi
   string namespace, // this will be the namespace aka lens
   uint256 handleId,
   address to, // this will be the owner of the profile
   uint256 timestamp
);

The handle gets linked to the profile automatically - an event emitted from TokenHandleRegistry

struct Token {
  uint256 id; // this will be the profileId
  address collection; // this will be the LensHub
}
struct Handle {
   uint256 id; // this will be the handleId
   address collection; // this will be the LensHandlesProxy
}
event HandleLinked(
    RegistryTypes.Handle handle,
    RegistryTypes.Token token,
    address transactionExecutor, // this will be address(0)
    uint256 timestamp
);

2. October 30th, 19:30-20:30 UTC - Migrate the Follow modules (approx. 2-3 hours)

1. If the legacy fee follow module is set, it will be replaced with the new fee follow module

2. If the profile follow module is set, we will remove it completely (will be address(0) in the follow module event below).

3. Event - It emits the same event as it would if the profile set this - the event emits from LensHub

event FollowModuleSet(
   uint256 indexed profileId,
   address followModule, // will be address(0) if removed
   bytes followModuleReturnData, // encoded with new fee follow module data or empty bytes if removed
   address transactionExecutor, // will be address(0)
   uint256 timestamp
);

3. October 30th, 21:30-22:30 UTC - Migrate the Follows (approx. 3 - 7 days for full completion)

Key points to note:

1. If you are an active user at the top of the migration list, this will be done much faster than non-active users (in the first 0-4 hours). It will take 3-7 days for the full completion of the migration of EVERY profile.

2. If you login into the API, it will be put in the queue to migrate, so this will be within 0-4 hours of being added to the queue. If you are active and using the protocol, you will be migrated much faster than non-active users.

3. The API will already apply to the state of the new follows optimistically. Any gated content at this time protected by the `following only` will only work once the migration has been completed; as noted above, the migration will be much faster for people using the apps. Any V1 publications that had gated content will still be decryptable if you pass the access control.

4. Event - It emits the same event as it would if the profile followed - the event emits from the LensHub

event Followed(
   uint256 indexed followerProfileId,
   uint256 idOfProfileFollowed,
   uint256 followTokenIdAssigned,
   bytes followModuleData,
   bytes processFollowModuleReturnData,
   address transactionExecutor, // this will be address(0)
   uint256 timestamp
);

Final milestones for V2 Upgrade

4. November 3rd to November 12th - Migration will be complete and all transactions settled.

5. November 30th - Upgrade to remove migration code.

6. November 30th - Scale down resources on V1 API as you can get all the data on V2.

7. January 30th, 2024 - Make V1 API route to V2 API and shutdown the V1 API after 3 months of supporting V1 API reads. As mentioned above, we will not be making any enhancements or fixes in the Lens V1 API after the migration.

As we move along the structured path of this migration, each step will ensure a smooth transition and unveil the powerful possibilities of social primitives through Lens V2. Transitioning to V2 is more than just adopting a new protocol; it's about welcoming a fundamental shift towards a more open, adaptable, and value-sharing social environment. Lens V2 showcases the essence of social primitives, reflecting our lively developer community's dedication to building a more connected and user-focused social realm. This migration is the next step towards creating a space where our developers can experiment, innovate, and add to the rich tapestry of web3 social. This journey brings us nearer to a digital world where collective creativity and innovation flourish freely.

While V2 represents a big step forward for web3 social, we’re still early. We’re excited to share more updates with our developer community in the coming months. In the meantime, if you or your team need any support please reach out to Nader Dabit (nader.lens) to join the Developer Garden.