Add migration guide

[devendran-m]

This PR copies Michael's Migration Guide draft(GitBook version) to docs-redux.

This PR also includes the pointers Ed highlighted in a couple of L1 and Sprint planning meetings. These sections are highlighted with the comment "Placeholder—Core Team input required", which seeks feedback and input to expand the content needed for exchanges.

Related Issue - https://github.com/casper-network/Governance/issues/529

Note:

• The changes were tested locally, and the result is included in the PR.

Screenshot:

Test result PDF:
Casper_2.0_Migration_Guide_for_Crypto_Exchanges _ CasperDocs-Redux.pdf

[davidatwhiletrue]

@devendran-m I've added to comments content for .NET SDK and Go SDK .

[davidatwhiletrue]

@devendran-m
Content for C# SDK:

• The appropriate SDK to upgrade to is the latest v3.x release found [here](https://github.com/make-software/casper-net-sdk/releases).
• Typical use case examples (connect to RPC, send a transfer, etc.) can be found in [the Examples folder](https://github.com/make-software/casper-net-sdk/tree/casper-2.0.0/Docs/Examples).
• To upgrade your integration, follow the document [Migration from Casper .NET SDK v2.x to v3.0](https://github.com/make-software/casper-net-sdk/blob/casper-2.0.0/Docs/Articles/Casper20MigrationGuide.md)

[devendran-m]

Thanks @davidatwhiletrue ,

I've incorporated your comments in the commit - ff82e88

Please review and let me know in case of any other changes.

cc: @KMCreatesWorlds

[davidatwhiletrue]

@devendran-m
Content for Go SDK:

• The appropriate SDK to upgrade to is the latest v2.x release found [here](https://github.com/make-software/casper-go-sdk/releases).
• Typical use case examples (connect to RPC, send a transfer, etc.) can be found in the [README](https://github.com/make-software/casper-go-sdk/blob/master/README.md).

[devendran-m]

Thanks @davidatwhiletrue ,

I've incorporated your comments in the commit - ff82e88

Please review and let me know in case of any other changes.

cc: @KMCreatesWorlds

[devendran-m]

Hi @ihor ,
This is the migration guide PR.

[darthsiroftardis]

Remove the word legacy and move Casper 1.x out of the parentheses

[darthsiroftardis]

So overall this document feels incomplete to me.

1. We need to mention that 1.x structures like Deploys are being deprecated, so while they will continue to work 2.x, they're due to be phased out and exchanges should understand that new types like TransactionV1 are the go forward.
2. Additionally, the sidecar needs mentioning as well, especially if certain exchanges run their own node, which means we need to guide them on the fact that RPC component now resides on the sidecar, which this document doesn't mention
3. The document keeps mentioning that its 'recommended' to be using the latest SDK release. It should be clear that updating to a new SDK will become necessary when addressable entity becomes enabled, which will require the exchanges to be using an SDK that is compatible with the Entity go forward.

[zajko]

Should the link point to the changelog? when will we instantiate it?

[devendran-m]

Thanks, @darthsiroftardis and @zajko ,
I've incorporated the changes in the latest commit 3f8c52248dc059c617f58ffd0b6aa6b1331c9a04.
Yes, we should be pointing to the change log and I need your help in getting the change log linked here.

[ihor]

Typo in, should be removed together with the comma

[zajko]

"Deploys have been renamed to Transactions" is misleading. Transactions are a higher-order concept which encapsulate both Deploys and V1 transactions. Transaction is a polymorphic data structure that, for now is either a Deploy (which should be compliant with the 1.x definition) or a V1

[zajko]

Also,
"Casper 2.0 implements a number of changes to the JSON RPC interface of the node"
The node no longer has a json rpc interface.

[devendran-m]

Thanks, @zajko ,
I've incorporated the possible and required changes in the latest commit 3f8c52248dc059c617f58ffd0b6aa6b1331c9a04.

[zajko]

"you may not have to make any changes prior to mainnet activation of Casper 2.0. "
That statement is not precise. Although the account-put-deploy JSON RPC method should accept the same structure of the input data, the result of "info_get_deploy" is not backwards compatible with 1.x.
So the only way an exchange would not need to do any changes is if they wouldn't care for the results of an execution (?)

[devendran-m]

Thanks, @zajko ,
I've incorporated the possible and required changes in the latest commit 3f8c52248dc059c617f58ffd0b6aa6b1331c9a04.

[zajko]

Is the json rpc changes section TBD or are they somewhere else?

[devendran-m]

Thanks, @zajko ,
I've incorporated the possible and required changes in the latest commit 3f8c52248dc059c617f58ffd0b6aa6b1331c9a04. I have linked the existing Casper 2.0 page that explains the 1.x vs 2.0 JSON RPC changes. Please let me know if that's the appropriate link we can use in this context.

[zajko]

I think we should have the detailed document explaining the differences? Who is responsible for creating that document?
Also are we talking about the JSON RPC API or do we want to explain in details how the internal protocol data changed?

[devendran-m]

Thanks, @zajko ,
I've incorporated the possible and required changes in the latest commit 3f8c52248dc059c617f58ffd0b6aa6b1331c9a04.
With regards to internal protocol data, I think it don't have to as detailed in the migration guide. However, please correct if my understanding is incorrect.

[zajko]

I agree with what @darthsiroftardis wrote, additionally:

• we need to explain that an operator which wants to have a forward facing API needs to turn on binary-port (since sidecar uses it). But in the same time the binary-port doesn't need to be a public port (it only needs to be exposed to sidecar)
• I'm not sure what are we aiming at in this document. If we want to provide a minimal guide on how to migrate - I would focus on explaining how to use 1.x deploys in a 2.x node - stressing that sidecars account_put_deploy should be compatible with 1.x node account_put_deploy, but sidecars info_get_deploy isn't 100% compatible with 1.x nodes info_get_deploy
• We need a section on the SSE feed changes

[devendran-m]

I agree with what @darthsiroftardis wrote, additionally:

• we need to explain that an operator which wants to have a forward facing API needs to turn on binary-port (since sidecar uses it). But in the same time the binary-port doesn't need to be a public port (it only needs to be exposed to sidecar)
• I'm not sure what are we aiming at in this document. If we want to provide a minimal guide on how to migrate - I would focus on explaining how to use 1.x deploys in a 2.x node - stressing that sidecars account_put_deploy should be compatible with 1.x node account_put_deploy, but sidecars info_get_deploy isn't 100% compatible with 1.x nodes info_get_deploy
• We need a section on the SSE feed changes

Thanks, @zajko ,
I've incorporated the possible and required changes in the latest commit 3f8c52248dc059c617f58ffd0b6aa6b1331c9a04.

[ihor]

Let's shorten the interfaces associated with interacting with the network to the API interfaces

[ihor]

Technically, there should be an Oxford comma after the protocol in the node software, the protocol, and the interfaces, but I don't want to start a fight here. Let's just make sure we use the oxford comma consistently.

[ihor]

Inconsistent capitalization of mainnet. It's capitalized in all (most of?) other places in the documentation Mainnet

[ihor]

Can we shorten crypto exchanges that offer $CSPR pairs, allow for $CSPR deposits and withdrawals and/or allow their users to stake $CSPR to crypto exchanges that work with the $CSPR token?

[ihor]

This migration guide will help you determine whether, and if so - how, to migrate your integration in prepartion for the network upgrade.

1. Typo preparation
2. Typo hyphen - instead of dash –
3. Let's replace migration here with update
4. There shouldn't be a comma after how

[ihor]

We can remove this paragraph w/o loosing information or clarity.

[ihor]

Let's change migrate to update here

[ihor]

"This migration guide will help you determine whether, and if so - how, to migrate your integration in prepartion for the network upgrade.

More information about the specific changes in, and features introduced by Casper 2.0 can be found here (LINK).

This migration guide aims at listing down the key information required for exchanges to make the necessary changes on their side to become Casper 2.0 ready.

Should I migrate my integration?

Exchanges have different levels of integration with Casper Network, and offer different subsets of functionality relating to $CSPR to their user base. Depending on the specifics of your integration, you may or may not have to migrate your integration prior to the mainnet launch of Casper 2.0. The table below helps you determine your next steps, if any."

The above piece of text contains repeated information. Similarly, the table seems to be unnecessarily verbose. What about replacing them with the following?

This guide should help you determine if any changes are needed on your end and, if so, how to update your integration in preparation for the network upgrade.

Should I update my integration?

Integration type	Required actions
Indirect integration through a 3rd party partner	No migration required, assuming the partner updates their integration
Running a node	Node software upgrade is required
Direct RPC API interaction	Adjustments to new response structures is required. Deprecated methods should be replaced with their newer alternatives
Interaction through an SDK	Upgrade to a Casper 2.0 compatible version is required

More information about the specific changes in, and features introduced by Casper 2.0 can be found here.

[ihor]

If we shrink the section with the table we can reduce this title to just "Integration types"

[ihor]

We have a separate section for the RPC API integration. Mentioning it here seems to be redundant. At the same time, this section doesn't mention anything about the actual changes in how the API is functioning in 2.0. We can find that information in the "RPC integration" section, but:
It's not applicable to the pure RPC integration, when the consumer isn't running their own node
It's unnecessarily verbose and partially incorrect at the same time (for example the SSE part)
Let's change this section to something like:

In Casper 2.0, the JSON RPC API is moved from the node to an accompanying software called Casper Sidecar. The sidecar communicates with the node via a binary protocol and exposes a familiar JSON RPC interface to the end users. It's still possible to fetch information directly from the node using the binary protocol; however, at this moment, the required libraries exist only for the Rust language.

The sidecar could be run on the same machine as the node or on a separate instance. Multiple sidecars could be run against one node to increase availability.

SSE API users can optionally configure the sidecar to store the SSE events in an external database. The current options are SQLite or PostgreSQL.

More information about the sidecar configuration can be found in the corresponding documentation. Also, before the Mainnet upgrade, the Casper team will provide the upgrade instructions to the node operators with reasonable default configuration options.

[zajko]

"the required libraries exist only for the Rust language."
If you're referring to casper-binary-port-client - we don't intend to release it in the near future AFAIK so I wouldn't mention it.

I would also omit details like storing SSE events since it's not relevant to the migration of exchanges.

[ihor]

As mentioned in my previous comment, the section above doesn't belong here.

[ihor]

That's not correct in terms of the RPC interface. A new type of transaction called TransactionV1 is introduced alongside the Deploy type.

[ihor]

The RPC integration section doesn't provide much information about what has to be changed, essentially sending the reader to check the RPC schema by themselves.

The above has to be rewritten to include the list of changes in the RPC protocol divided into two parts:

1. Change in types with correspondences between the semantically identical types (Deploy and TransactionV1, Block and BlockV2)
2. Changes in the RPC methods that clearly describe which methods are deprecated and what are their newer alternatives.

[ihor]

Additionally, this section is a very heavy lift. Do we know of case where somebody integrates with the RPC interface directly w/o an SDK?

[ihor]

The two paragraphs above kind of repeat themselves that "you may or may not need to upgrade". We should replace the intro with more specifics of how new SDKs operate to help the reader understand the changes and make the decision. We could replace it with something like this:

Casper 2.0 introduces changes essential for the network’s future evolution, which also include modifications to data structures that impact API responses. Since historical blockchain data cannot be altered due to cryptographic signatures, both legacy and new data structures will coexist in Casper 2.0 and be returned by the API.

To simplify the transition for developers, we prepared new backward and forward-compatible Casper SDKs that provide a uniform data interface across both Casper 1.5.x and Casper 2.0. This ensures that developers can work with consistent data types, regardless of the network version in which the data was created.

Upgrading to a new version of Casper SDKs makes it possible to have one integration that guarantees future compatibility with Casper 2.0 while maintaining the existing compatibility with Casper 1.5. The network upgrade will require no changes in the consumer code, ensuring no disruption in the service.

[ihor]

We should not include not-enabled functionality in the migration guide. It unnecessarily overloads the reader w/o providing any clear value.

[ihor]

Is there any reason why we use a table here? It's not formatted conventionally. Having subsections for each language would probably be more readable:

Additionally, the last row says to contact the Casper team but doesn't provide any way how to do that.

[devendran-m]

Hi @ihor ,
cc: @zajko , @darthsiroftardis , @EdHastingsCasperAssociation

I've addressed most of your comments in the latest commit - 1b2d0ec.
Regarding the information about the sidecar, transactions, and the difference between 1.x and 2.0, I have added the details shared by Jakub and Karan in their earlier review cycle. I also request that the core team review and share their input/feedback to elaborate the guide.