migration from v1.0

SUMMARY.md

@@ -10,6 +10,7 @@
     - [Swift Client \(iOS\)](quick-start/wallets/swift.md)
     - [Kotlin Client \(Android\)](quick-start/wallets/kotlin.md)
 - [Session Management](session-management.md)
+- [Migrating from v1.0](migration.md)
 - [Mobile Linking](mobile-linking.md)
 - [Technical Specification](tech-spec.md)
 - [JSON-RPC Methods](json-rpc/README.md)

migration.md

@@ -0,0 +1,51 @@
+# Migrating from v1.0
+
+WalletConnect v1.0 and v2.0 offer essentially the same end-user experience however they work very differently internally. This means that developers will have to consider different APIs and SDKs. Additionally some UX considerations need to be made when integration v2.0
+
+## Migration schedule
+
+WalletConnect v2.0 is **NOT** backwards-compatible with v1.0. Therefore we must coordinate a migration schedule to ensure end-users do not suffer from this transition.
+
+Most importantly we must migrate Wallets before Dapps can start supporting v2.0. This is because Wallets can support both versions in parallel and route connection requests to corresponding clients using the version number specified in the URI present in the QR Code or Deep Link.
+
+Once we reach a signficant quota of Wallets supporting v2.0 then we can start migrating Dapps as they will be able to simply upgrade the major version of their packages on NPM.
+
+## Multi-Chain support
+
+Most interfaces are very similar to the previous version but the most constrating difference between the two versions comes from its multi-chain support.
+
+WalletConnect v1.0 mimic a lot of its behavior from Metamask's browser extension which meant that sessions tracked a single chainId, an accounts array and wallets controlled the chainId while dapps followed.
+
+WalletConnect v2.0 instead allows dapps to request a set of chains as part of the scope of the session and Wallets respond with a success or error message when the compatibility is met. Additionally this means that the Wallet no longer controls the chainId of the chain but instead the session tracks multiple chainId's. Finally the Wallet will expose one or many accounts matching each of the chains requested by the Dapp and these can be updated on the session state during its lifetime.
+
+## Chain-Agnostic interface
+
+Previously on v1.0, WalletConnect expected only EVM-compatible Wallets and Dapps to use its protocol to interoperate. This assumption however brought its own constraints which disable other chain ecosystems to use meet compatibility and utilize the protocol.
+
+WalletConnect v2.0 introduces a set of JSON-RPC methods that are permissioned to use within the session's lifetime. This means that a Dapp can request a minimum set of methods that requires to meet compatibility with the Wallet which can be responded with a success or error message when the compatibility is met. Additionally this means that not only the Dapp can determine if the Wallet can sign transactions and/or messages for the chain it needs but it also can detect support for experimental methods (eg. eth_signTypedData). Finally the Wallet can upgrade the set of methods it exposes during its session lifetime.
+
+## Session Lifetime
+
+Previously on v1.0, WalletConnect had indefinite session lifetime which meant that clients would persist the session state until one of the clients emitted an event to disconnect. This however introduced a lot of stalled session states where one of the clients would loose its state and never emitted an event to disconnect.
+
+Therefore WalletConnect v2.0 introduces expery timestamps for sessions which are currently defaulted to 7 days. This means that independent of the disconnect event not being emitted by a peer client then a client will disconnect and delete the session state after expiry is met.
+
+Session requests include a TTL (time to live) value which can extend the default lifetime (7 days) of the session. Also the session expiry timestamp is calculated by the responder client which then shares the timestamp on its session response.
+
+## Pairings & Sessions
+
+The newest concept introduced with WalletConnect v2.0 which wasn't present in WalletConnect v1.0 were the pairings. Pairings which are special-purpose sessions used to propose new sessions which have a default lifetime of 30 days. Whenever a QR Code or Deep Link is generated to connect a Dapp and a Wallet it is used to establish a pairing, therefore when a session is expired or terminated it no longer requires clients to pair again if they still have an active pairing.
+
+Pairings have longer expiration than Sessions because they are meant to be re-used for session proposals and they can request an infinite number of session proposals between Dapps and Wallets
+
+## Single Client
+
+Previously on v1.0, WalletConnect managed a session per each client which itself maintained a WebSocket connection with the Relay (aka Bridge) server. This design was not performant and it also introduced a lot of complexity managing multiple sessions specially for Wallets.
+
+WalletConnect v2.0 clients are more monolithic but manage multiple sessions within one single client and transport all messages through a single WebSocket connection. This also means that WalletConnect v2.0 clients also manage their storage to persist the state of multiple sessions and consequently also pairings as well.
+
+## Message Acknowledgement
+
+Perhaps the biggest drawback of the WalletConnect v1.0 was that clients did not acknowledge received messages from the server and didn't track the history of JSON-RPC requests received
+
+WalletConnect v2.0 clients track all JSON-RPC requests sent and received with the client, can ignore duplicates and acknowledge messages that were receives. This means basically that independently of the server or node that WalletConnect v2.0 is connected to it won't affect the behavior of a session and it's state can be restored without interruptation.