From 2a0555058fe7bded356e51579d1b01718d69bbd0 Mon Sep 17 00:00:00 2001 From: David Hernando Date: Mon, 8 Jul 2024 18:27:48 +0200 Subject: [PATCH 1/7] WIP migration guide Signed-off-by: David Hernando --- Docs/Articles/CondorMigrationGuide.md | 118 ++++++++++++++++++++++++++ 1 file changed, 118 insertions(+) create mode 100644 Docs/Articles/CondorMigrationGuide.md diff --git a/Docs/Articles/CondorMigrationGuide.md b/Docs/Articles/CondorMigrationGuide.md new file mode 100644 index 0000000..53810d5 --- /dev/null +++ b/Docs/Articles/CondorMigrationGuide.md @@ -0,0 +1,118 @@ +# Migration from Casper .NET SDK v2.x to v3.0 + +To migrate your application from Casper .NET SDK v2.x to Casper .NET SDK v3.0 you'll need to make several +changes on your code. The good news is that with version 3 of the SDK your application will be compatible with +Casper v1.5.6 as well as with Casper v2.0 (aka Condor). + +## Types + +### Blocks + +With Condor, block records use a new format to accommodate more types of Transactions and surface previously embedded +information. New blocks will use the new format; historical blocks retain their original format. + +In the SDK, this mean you can deal with two versions of blocks. `BlockV1` are blocks produced before Condor, i.e. within +Casper 1.x protocol version. `BlockV2` are blocks produced after Condor upgrade. + +To facilitate handling different versions, the SDK implements the type `Block` which can be either a V1 or V2 type in +the network. This type contains all the data you may want to query: + +```csharp +public class Block +{ + public int Version { get; init; } + public string Hash { get; init; } + public string AccumulatedSeed { get; init; } + public ulong EraId { get; init; } + public ulong Height { get; init; } + public string ParentHash { get; init; } + public string ProtocolVersion { get; init; } + public bool RandomBit { get; init; } + public string StateRootHash { get; init; } + public string Timestamp { get; init; } + public EraEnd EraEnd { get; init; } + public UInt16 CurrentGasPrice { get; init; } + public Proposer Proposer { get; init; } + public string LastSwitchBlockHash { get; init; } + public List Transactions { get; init; } + public List> RewardedSignatures { get; init; } +} +``` + +Note that `Block` does not have a header nor body parts. + +Also, be aware that some properties may be `null` if they're not part of the versioned block. For +example, `LastSwitchBlockHas` is present only for V2 blocks. + +#### Recovering the versioned block object + +If, for any reason, you need to work with the original format of the block, you can cast a `Block` to a `BlockV1` +or `BlockV2`. For example: + +```csharp +if (block.Version == 2) { + var blockv2 = (BlockV2)block; + // ... +} else if (blockVersion == 1) { + var blockv1 = (BlockV1)block; + // ... +} +``` + +#### EraEnd + +`EraEnd` structure also differs for switch blocks produced before and after Condor. In most cases you can just use +the `EraEnd` object from the common `Block` class. But again, if you need it, you can recover an `EraEndV1` object from +a V1 block: + +```csharp +if (block.Version == 1) { + var blockv1 = (BlockV1)block; + var eraEnd = blockv1.Header.EraEnd; + // ... +} +``` + +#### Transactions + +Blocks produced on Casper 1.x contain a list of deploys which differentiate between native transfers and all other types +of deploys. On Condor, transactions (this includes legacy deploys too) have a category field which determines the +processing lane the transaction is sent to. The chainspec of the network determines the properties of each lane: + +1. Maximum transaction size in bytes for a given transaction in a certain lane. +2. Maximum args length size in bytes for a given transaction in a certain lane. +3. Transaction gas limit size in motes for a given transaction in a certain lane. +4. The maximum number of transactions the lane can contain for one block. + +The categories (i.e. lanes) defined so far are: + +1. Mint (native CSPR transfers) transactions +2. Auction (native interaction with the Auction contract) transactions +3. Install/Upgrade transactions +4. Large transactions +5. Medium transactions +6. Small transactions + +A `Block` contains a list of transactions: + +```csharp +public List Transactions { get; init; } +``` + +For each transaction, the category, the Version (either a legacy `Deploy` or the new `TransactionV1`) and its `Hash` is +provided. + +`Deploy`s in V1 blocks are categorized as `Mint` for native transfer deploys and `Large` for all the rest. + +In this list, each transaction has + +#### Block height type + +The type to represent block height is now `ulong` everywhere. `int` was used in some methods or types in the previous +version. That's not the case with v3. + +## Other changes + +### Checksums (CEP-57) + +On SDK v3 only public keys are checksummed. The rest of keys and hashes are not checksummed anymore. From 9992e48619bd233156fc5bbd5e1b9e4874ca4a39 Mon Sep 17 00:00:00 2001 From: David Hernando Date: Tue, 9 Jul 2024 12:08:37 +0200 Subject: [PATCH 2/7] WIP Signed-off-by: David Hernando --- Docs/Articles/CondorMigrationGuide.md | 106 ++++++++++++++++++++++++-- 1 file changed, 100 insertions(+), 6 deletions(-) diff --git a/Docs/Articles/CondorMigrationGuide.md b/Docs/Articles/CondorMigrationGuide.md index 53810d5..16a7312 100644 --- a/Docs/Articles/CondorMigrationGuide.md +++ b/Docs/Articles/CondorMigrationGuide.md @@ -4,9 +4,11 @@ To migrate your application from Casper .NET SDK v2.x to Casper .NET SDK v3.0 yo changes on your code. The good news is that with version 3 of the SDK your application will be compatible with Casper v1.5.6 as well as with Casper v2.0 (aka Condor). -## Types +This guide does not replace other Condor-related documents that introduce the changes in the new version of the Casper +network +software. We encourage the reader to get familiar with the new concepts first. -### Blocks +## Blocks With Condor, block records use a new format to accommodate more types of Transactions and surface previously embedded information. New blocks will use the new format; historical blocks retain their original format. @@ -44,7 +46,7 @@ Note that `Block` does not have a header nor body parts. Also, be aware that some properties may be `null` if they're not part of the versioned block. For example, `LastSwitchBlockHas` is present only for V2 blocks. -#### Recovering the versioned block object +### Recovering the versioned block object If, for any reason, you need to work with the original format of the block, you can cast a `Block` to a `BlockV1` or `BlockV2`. For example: @@ -59,7 +61,7 @@ if (block.Version == 2) { } ``` -#### EraEnd +### EraEnd `EraEnd` structure also differs for switch blocks produced before and after Condor. In most cases you can just use the `EraEnd` object from the common `Block` class. But again, if you need it, you can recover an `EraEndV1` object from @@ -73,7 +75,7 @@ if (block.Version == 1) { } ``` -#### Transactions +### Transactions included in a block Blocks produced on Casper 1.x contain a list of deploys which differentiate between native transfers and all other types of deploys. On Condor, transactions (this includes legacy deploys too) have a category field which determines the @@ -106,11 +108,103 @@ provided. In this list, each transaction has -#### Block height type +### Block height type The type to represent block height is now `ulong` everywhere. `int` was used in some methods or types in the previous version. That's not the case with v3. +## Account/Contract Merge + +On Condor, accounts and contracts are stored with the new type `AddressableEntity`. The `EntityKind` property in +this type permits to know whether the record is an `Account`, a stored `SmartContract` or a `System` contract. + +### GetEntity RPC method + +Use the new method`GetEntity(IEntityIdentifier)` in the RPC interface to retrieve a +record. `PublicKey`, `AccountHashKey` +and `AddressableEntityKey` implement the `IEntityIdentiifer` interface and can be used to retrieve +and `AddressableEntity` from the network. While `PublicKey` and `AccountHashKey`are known, the `AddressableEntitykey` is +new but the developer must come familiar with it to work with Condor. Some examples of this key are: + +``` +entity-account-2f3fb80d362ad0a922f446915a259c9aaec9ba99292b3e50ff2359c458007309 +entity-contract-a5cf5917505ef60a6f0df395dd19e86a0f075d00f2e6ce49f5aa0e18f6e26f5d +entity-system-a1b5f200a58533875ef83cb98de14f128342b34162cbc14d4f41f3ccbc451dc3 +``` + +### Legacy accounts + +Existing accounts are migrated either during the Condor upgrade or when they interact with the network for +the first time after the upgrade. The exact time depends on the `chainspec` agreed for the Condor upgrade. Hash values +for the `AccountHashKey` and the `EntityKey` are shared and remain unchanged for migrated accounts. + +Non-migrated accounts can be retrieved also with the new `GetEntity` method. In this case, the response contains the +account info in the `LegacyAccount` property instead of in the `Entity` property. + +Alternatively, the legacy method `GetAccountInfo` works also for non-migrated accounts. + +### Contract information + +Similar to accounts, contract records are migrated also to the new `AddressableEntity`. After the migration, +only `GetEntity` method can be used to retrieve contract information. Hash values for contracts and packages remain +unchaged for the migrated records. + +To retrieve information about the contract package use the `QueryGlobalState` method with the `PackageKey` of the +contract. + +### Backwards compatibility + +When using the SDK v3 with a Casper v1.x network, only `GetAccountInfo` can be used to retrieve account information. For +contract and package information use `QueryGlobalState`. + +## Balances + +The new `NoFee` mode in Condor introduces the concept of a 'balance hold'. In this mode of operation, for each +transaction +the network holds the amount paid for its execution in the paying purse. Thus, entities have a total balance and an +available balance, where available balance is equal to the total balance minus the balance holds. + +To get a detailed information of an entity balance use the new method `QueryBalanceDetails(IPurseIdentifier)` with a +purse identifier. `PublicKey`, `AccountHashKey`, `AddressableEntityKey` and `URef` keys implement the `IPurseIdentifier` +interface and +can be used to retrieve the balance details for an entity. + +`GetAccountBalance` has been renamed to `GetBalance` since this method can be used for any type of entity, not only for +accounts. + +## Deploys and Transactions + +Condor introduces a new transaction model to support advanced use cases. While `Deploy`s continue to work in Condor, +this type is deprecated and Casper recommends to switch to the new `TransactionV1` type. + +Similar to the `DeployTemplates` class which provided deploy templates for most common use cases, we plan to implement +a `TransactionV1Templates` class for the new model of transactions in a next release of this SDK. + +Use the new method `PutTransaction` to send a `TransactionV1` to the network. To retrieve an accepted transaction use +the new `GetTransaction` method. `GetTransaction` can be used also to retrieve a `Deploy`. For non processed +transactions the `ExecutionInfo` in the response is null. Upon processing, this property contains all information about +the execution, including cost, payments, errors (if any) and execution effects. + +### Payments and costs + +For a transaction (old and new types) processed in Condor, the execution results object contain three properties related +to the gas consumed and the CSPR tokens paid: + +- `limit`: The maximum allowed gas limit for the transaction. +- `consumed`: How much gas was consumed executing the transaction. +- `cost`: How much CSPR was paid/held for the transaction. + +In the `NoFee` model, the user does not specify any amount for payment. Instead, he must use the `Fixed` pricing mode +with a gas price tolerance. The network chainspec defines the gas limit for each of the transaction categories (see +'Transactions included in a block' section above). Then for each era the network determines a gas price based on the +previous era load. This price works as a multiplier for the consumed gas and relates to the gas price +tolerance specified in the transaction. If the tolerance is lower than the gas price, the transaction won't be +processed. The consumed gas in a transaction must be always lower than the limit or it will fail with an out of gas +error. Finally, the cost in the no-fee model is the limit multiplied by the gas price. + +### Execution results + + ## Other changes ### Checksums (CEP-57) From 60d7fb92d9db886c6d8f78d8cd209610e7caccea Mon Sep 17 00:00:00 2001 From: David Hernando Date: Tue, 9 Jul 2024 12:47:37 +0200 Subject: [PATCH 3/7] WIP Signed-off-by: David Hernando --- Docs/Articles/CondorMigrationGuide.md | 30 ++++++++++++++++++++++++++- 1 file changed, 29 insertions(+), 1 deletion(-) diff --git a/Docs/Articles/CondorMigrationGuide.md b/Docs/Articles/CondorMigrationGuide.md index 16a7312..f72ce91 100644 --- a/Docs/Articles/CondorMigrationGuide.md +++ b/Docs/Articles/CondorMigrationGuide.md @@ -55,7 +55,7 @@ or `BlockV2`. For example: if (block.Version == 2) { var blockv2 = (BlockV2)block; // ... -} else if (blockVersion == 1) { +} else if (block.Version == 1) { var blockv1 = (BlockV1)block; // ... } @@ -204,9 +204,37 @@ error. Finally, the cost in the no-fee model is the limit multiplied by the gas ### Execution results +The `ExecutionResult` class is a versioned object. Deploys processed before Condor upgrade are stored in the global +state as `ExecutionResultV1`records. And deploys and transactions processed after Condor upgrade are stored +as `ExecutionResultV2` records. + +The `GetTransaction` method always returns a `ExecutionResult` instance regardless the version. It has the same fields +than `ExecutionResultV2`. The user can obtain the original structure with casting this instance to the correct version: + +```csharp +if (executionResult.Version == 2) { + var executionResultV2 = (ExecutionResultV2)executionResult; + // ... +} else if (executionResult.Version == 1) { + var executionResultV1 = (ExecutionResultV1)executionResult; + // ... +} +``` + +The `Effect` property contains a list of `Transforms` that modify the global state. Note that the `ExecutionEffect` +which contained also a list of operations in addition to the transforms has been removed in Condor execution results. ## Other changes +### Last switch block hash + +For a Condor network, it is possible to get the latest switch block hash with the `GetNodeStatus` method. The response +contains the `LatestSwitchBlockHash` property with this value. + +Also, for blocks produced in Casper 2.0, the `Block` instance contains the previous switch block hash in +the `LastSwitchBlockHash` property. + ### Checksums (CEP-57) On SDK v3 only public keys are checksummed. The rest of keys and hashes are not checksummed anymore. + From 5c6ab921cb5e6889ab2df9dfc80f7de05c4fc23f Mon Sep 17 00:00:00 2001 From: David Hernando Date: Tue, 9 Jul 2024 16:42:21 +0200 Subject: [PATCH 4/7] WIP migration guide Signed-off-by: David Hernando --- Docs/Articles/CondorMigrationGuide.md | 43 +++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/Docs/Articles/CondorMigrationGuide.md b/Docs/Articles/CondorMigrationGuide.md index f72ce91..ec35bb0 100644 --- a/Docs/Articles/CondorMigrationGuide.md +++ b/Docs/Articles/CondorMigrationGuide.md @@ -224,6 +224,49 @@ if (executionResult.Version == 2) { The `Effect` property contains a list of `Transforms` that modify the global state. Note that the `ExecutionEffect` which contained also a list of operations in addition to the transforms has been removed in Condor execution results. +## Auction contract + +The auction contract also has changed in Condor. If your application tracks validator bids, rewards and delegators, +you'll need to rework the way network responses are parsed and interpreted. A complete description of the changes cannot +covered in this guide. + +## Server Sent Events + +The `ServerEventsClient` class can listen to both an event stream from a `v1.x` node as well as from `v2.x`. + +### Blocks + +`BlockedAdded` event contains a `Block` object. When needed, the original block structure `BlockV1` or `BlockV2` can be +obtained with cast operator as described above. + +### Transactions + +On Condor, the events `DeployAccepted`, `DeployProcessed` and `DeployExpired` are replaced with the +equivalent `TransactionAccepted`, `TransactionProcessed` and `TransactionExpired`. These new events are emitted for +both `Deploy` and `TransactionV1` types of transactions. + +A `TransactionAccepted` event contains a `Transaction` property with either a `Deploy` or a `TransactionV1`. + +`TransactionProcessed` and `TransactionExpired` events contain a `TransactionHash` property with either a deploy hash or +a transaction version 1 hash. + +### Finality signatures + +The `FinalitySignature` event contains an instance of the versioned `FinalitySignature` class. Version 2 of this type is +an extension that contains all properties in version 1 plus the block height and the chain name hash. + +The user can obtain the original structure with casting this instance to the correct version: + +```csharp +if (finalitySignature.Version == 2) { + var finalitySignatureV2 = (FinalitySignatureV2)finalitySignature; + // ... +} else if (finalitySignature.Version == 1) { + var finalitySignatureV1 = (FinalitySignatureV1)finalitySignature; + // ... +} +``` + ## Other changes ### Last switch block hash From a8c2c6bc27cb5ea9d723e9b689a24d5a9ae49358 Mon Sep 17 00:00:00 2001 From: David Hernando Date: Tue, 9 Jul 2024 17:23:42 +0200 Subject: [PATCH 5/7] Corrections. WIP. Signed-off-by: David Hernando --- Docs/Articles/CondorMigrationGuide.md | 152 ++++++++------------------ 1 file changed, 44 insertions(+), 108 deletions(-) diff --git a/Docs/Articles/CondorMigrationGuide.md b/Docs/Articles/CondorMigrationGuide.md index ec35bb0..a86cc2b 100644 --- a/Docs/Articles/CondorMigrationGuide.md +++ b/Docs/Articles/CondorMigrationGuide.md @@ -1,23 +1,14 @@ # Migration from Casper .NET SDK v2.x to v3.0 -To migrate your application from Casper .NET SDK v2.x to Casper .NET SDK v3.0 you'll need to make several -changes on your code. The good news is that with version 3 of the SDK your application will be compatible with -Casper v1.5.6 as well as with Casper v2.0 (aka Condor). +To migrate your application from Casper .NET SDK v2.x to Casper .NET SDK v3.0, you’ll need to make several changes to your code. The good news is that version 3 of this SDK keeps compatibility with Casper v1.5.6 nodes; therefore, once you update your application, it will work before and after the Condor upgrade. -This guide does not replace other Condor-related documents that introduce the changes in the new version of the Casper -network -software. We encourage the reader to get familiar with the new concepts first. +This guide outlines the changes necessary for your application. However, it's worth noting that it doesn't replace other Condor-related documents introducing the new concepts in Casper 2.0 or migration guides. We strongly advise the reader to understand these new concepts first, as they will significantly aid in grasping the changes. ## Blocks -With Condor, block records use a new format to accommodate more types of Transactions and surface previously embedded -information. New blocks will use the new format; historical blocks retain their original format. +With Condor, produced blocks are stored in a new format that extends the information contained compared to old blocks. Blocks produced before the upgrade keep their original format. Thus, the SDK implements `BlockV1` and `BlocV2` classes to handle old and new block formats, respectively. -In the SDK, this mean you can deal with two versions of blocks. `BlockV1` are blocks produced before Condor, i.e. within -Casper 1.x protocol version. `BlockV2` are blocks produced after Condor upgrade. - -To facilitate handling different versions, the SDK implements the type `Block` which can be either a V1 or V2 type in -the network. This type contains all the data you may want to query: +To facilitate handling different versions, the SDK also implements the type `Block`, which can represent either a V1 or V2 type in the network. This is the type obtained by default in the RPC queries and the SSE channel and contains all the data you may want to query: ```csharp public class Block @@ -41,15 +32,13 @@ public class Block } ``` -Note that `Block` does not have a header nor body parts. +Note that `Block` does not have a header or body parts. -Also, be aware that some properties may be `null` if they're not part of the versioned block. For -example, `LastSwitchBlockHas` is present only for V2 blocks. +Also, some properties may have a `null` value if they’re not part of the versioned block. For example, `LastSwitchBlockHas` is present only for V2 blocks and `null` for V1 blocks. ### Recovering the versioned block object -If, for any reason, you need to work with the original format of the block, you can cast a `Block` to a `BlockV1` -or `BlockV2`. For example: +If, for any reason, you need to work with the original format of the block, you can cast a Block into BlockV1 or BlockV2. For example: ```csharp if (block.Version == 2) { @@ -63,9 +52,7 @@ if (block.Version == 2) { ### EraEnd -`EraEnd` structure also differs for switch blocks produced before and after Condor. In most cases you can just use -the `EraEnd` object from the common `Block` class. But again, if you need it, you can recover an `EraEndV1` object from -a V1 block: +EraEnd structure also differs for switch blocks produced before and after Condor. In most cases, you can just use the EraEnd object from the common Block class. But again, if necessary, you can recover an EraEndV1 object from a Version 1 Block instance: ```csharp if (block.Version == 1) { @@ -77,16 +64,14 @@ if (block.Version == 1) { ### Transactions included in a block -Blocks produced on Casper 1.x contain a list of deploys which differentiate between native transfers and all other types -of deploys. On Condor, transactions (this includes legacy deploys too) have a category field which determines the -processing lane the transaction is sent to. The chainspec of the network determines the properties of each lane: +Blocks produced on Casper v1.x contain a list of deploys that differentiate between native transfers and all other types of deploys. On Condor, transactions (this includes legacy deploys too) have a category field that determines the processing lane to which the transaction is sent. The chainspec of the network determines the properties of each lane: 1. Maximum transaction size in bytes for a given transaction in a certain lane. 2. Maximum args length size in bytes for a given transaction in a certain lane. 3. Transaction gas limit size in motes for a given transaction in a certain lane. 4. The maximum number of transactions the lane can contain for one block. -The categories (i.e. lanes) defined so far are: +The categories (i.e., lanes) defined so far are: 1. Mint (native CSPR transfers) transactions 2. Auction (native interaction with the Auction contract) transactions @@ -101,30 +86,22 @@ A `Block` contains a list of transactions: public List Transactions { get; init; } ``` -For each transaction, the category, the Version (either a legacy `Deploy` or the new `TransactionV1`) and its `Hash` is -provided. - -`Deploy`s in V1 blocks are categorized as `Mint` for native transfer deploys and `Large` for all the rest. +The category, version (either a legacy Deploy or the new TransactionV1 type), and the hash are provided for each transaction. -In this list, each transaction has +`Deploy`s in V1 blocks are categorized as `Mint` for native transfer deploys and `Large` for all the rest. The same happens for legacy deploys sent to a Casper v2.x node. ### Block height type The type to represent block height is now `ulong` everywhere. `int` was used in some methods or types in the previous -version. That's not the case with v3. +version. That's not the case with Casper .NET SDK v3. ## Account/Contract Merge -On Condor, accounts and contracts are stored with the new type `AddressableEntity`. The `EntityKind` property in -this type permits to know whether the record is an `Account`, a stored `SmartContract` or a `System` contract. +On Condor, accounts and contracts are stored with the new type AddressableEntity. The EntityKind property in this type permits knowing whether the record is an Account, a stored SmartContract, or a System contract. ### GetEntity RPC method -Use the new method`GetEntity(IEntityIdentifier)` in the RPC interface to retrieve a -record. `PublicKey`, `AccountHashKey` -and `AddressableEntityKey` implement the `IEntityIdentiifer` interface and can be used to retrieve -and `AddressableEntity` from the network. While `PublicKey` and `AccountHashKey`are known, the `AddressableEntitykey` is -new but the developer must come familiar with it to work with Condor. Some examples of this key are: +Use the new method GetEntity(IEntityIdentifier) in the RPC interface to retrieve a record. PublicKey, AccountHashKey, and AddressableEntityKey implement the IEntityIdentiifer interface and can be used to retrieve an AddressableEntity from the network. While PublicKey and AccountHashKeyare known types from Casper v1.x, the AddressableEntitykey is new, but the developer must become familiar with it to work with Condor. Some examples of this key are: ``` entity-account-2f3fb80d362ad0a922f446915a259c9aaec9ba99292b3e50ff2359c458007309 @@ -134,82 +111,53 @@ entity-system-a1b5f200a58533875ef83cb98de14f128342b34162cbc14d4f41f3ccbc451dc3 ### Legacy accounts -Existing accounts are migrated either during the Condor upgrade or when they interact with the network for -the first time after the upgrade. The exact time depends on the `chainspec` agreed for the Condor upgrade. Hash values -for the `AccountHashKey` and the `EntityKey` are shared and remain unchanged for migrated accounts. +Existing accounts are migrated either during the Condor upgrade or when they interact with the network for the first time after the upgrade. The exact time depends on the `chainspec` agreed for the Condor upgrade. Hash values for the `AccountHashKey` and the `EntityKey` are shared and remain unchanged for migrated accounts. -Non-migrated accounts can be retrieved also with the new `GetEntity` method. In this case, the response contains the -account info in the `LegacyAccount` property instead of in the `Entity` property. +Non-migrated accounts can also be retrieved using the new `GetEntity` method. In this case, the response contains the account info in the `LegacyAccount` property instead of the `Entity` property. -Alternatively, the legacy method `GetAccountInfo` works also for non-migrated accounts. +Alternatively, the legacy method `GetAccountInfo` also works for non-migrated accounts. ### Contract information -Similar to accounts, contract records are migrated also to the new `AddressableEntity`. After the migration, -only `GetEntity` method can be used to retrieve contract information. Hash values for contracts and packages remain -unchaged for the migrated records. +Like accounts, contract records have also been migrated to the new `AddressableEntity`. After the migration, only the `GetEntity` method can be used to retrieve contract information. Hash values for contracts and packages remain unchanged for the migrated records. -To retrieve information about the contract package use the `QueryGlobalState` method with the `PackageKey` of the -contract. +To retrieve information about the contract package, use the `QueryGlobalState` method with the `PackageKey` of the contract. ### Backwards compatibility -When using the SDK v3 with a Casper v1.x network, only `GetAccountInfo` can be used to retrieve account information. For -contract and package information use `QueryGlobalState`. +When using the SDK v3 with a Casper v1.x network, only GetAccountInfo can be used to retrieve account information. For contract and package information use QueryGlobalState. ## Balances -The new `NoFee` mode in Condor introduces the concept of a 'balance hold'. In this mode of operation, for each -transaction -the network holds the amount paid for its execution in the paying purse. Thus, entities have a total balance and an -available balance, where available balance is equal to the total balance minus the balance holds. +The new `NoFee` mode in Condor introduces the concept of a ‘balance hold’. In this mode of operation, for each transaction, the network holds the amount paid for its execution in the paying purse. Thus, entities have a total balance and an available balance, where the available balance is equal to the total balance minus the balance holds. -To get a detailed information of an entity balance use the new method `QueryBalanceDetails(IPurseIdentifier)` with a -purse identifier. `PublicKey`, `AccountHashKey`, `AddressableEntityKey` and `URef` keys implement the `IPurseIdentifier` -interface and -can be used to retrieve the balance details for an entity. +To get detailed information on an entity balance, use the new method `QueryBalanceDetails(IPurseIdentifier)` with a purse identifier. `PublicKey`, `AccountHashKey`, `AddressableEntityKey`, and `URef` keys implement the `IPurseIdentifier` interface and can be used to retrieve the balance details for an entity. -`GetAccountBalance` has been renamed to `GetBalance` since this method can be used for any type of entity, not only for -accounts. +`GetAccountBalance` has been renamed to `GetBalance` since this method can be used for any type of entity, not only for accounts. ## Deploys and Transactions -Condor introduces a new transaction model to support advanced use cases. While `Deploy`s continue to work in Condor, -this type is deprecated and Casper recommends to switch to the new `TransactionV1` type. +Condor introduces a new transaction model to support advanced use cases. While `Deploy`s continue to work in Condor, this type is deprecated, and Casper recommends switching to the new `TransactionV1` type. -Similar to the `DeployTemplates` class which provided deploy templates for most common use cases, we plan to implement -a `TransactionV1Templates` class for the new model of transactions in a next release of this SDK. +Similar to the `DeployTemplates` class, which provides deploy templates for most common use cases, we plan to implement a TransactionV1Templates class for the new transaction model in the next release of this SDK. -Use the new method `PutTransaction` to send a `TransactionV1` to the network. To retrieve an accepted transaction use -the new `GetTransaction` method. `GetTransaction` can be used also to retrieve a `Deploy`. For non processed -transactions the `ExecutionInfo` in the response is null. Upon processing, this property contains all information about -the execution, including cost, payments, errors (if any) and execution effects. +Use the new method `PutTransaction` to send a `TransactionV1` to the network. Use the new `GetTransaction` method to retrieve an accepted transaction. Both methods can also be used to send and retrieve a Deploy. For unprocessed transactions, the ExecutionInfo in the response is `null`. Upon processing, this property contains all information about the execution, including cost, payments, errors (if any), and execution effects. ### Payments and costs -For a transaction (old and new types) processed in Condor, the execution results object contain three properties related -to the gas consumed and the CSPR tokens paid: +For a transaction (old and new versions) processed in Condor, the execution results object contains three properties related to the gas consumed and the CSPR tokens paid: - `limit`: The maximum allowed gas limit for the transaction. -- `consumed`: How much gas was consumed executing the transaction. -- `cost`: How much CSPR was paid/held for the transaction. +- `consumed`: Gas consumed executing the transaction. +- `cost`: CSPR paid/held for the transaction. -In the `NoFee` model, the user does not specify any amount for payment. Instead, he must use the `Fixed` pricing mode -with a gas price tolerance. The network chainspec defines the gas limit for each of the transaction categories (see -'Transactions included in a block' section above). Then for each era the network determines a gas price based on the -previous era load. This price works as a multiplier for the consumed gas and relates to the gas price -tolerance specified in the transaction. If the tolerance is lower than the gas price, the transaction won't be -processed. The consumed gas in a transaction must be always lower than the limit or it will fail with an out of gas -error. Finally, the cost in the no-fee model is the limit multiplied by the gas price. +In the NoFee model, the user does not specify any amount for payment. Instead, he must use the Fixed pricing mode with a gas price tolerance. The network chainspec defines the gas limit for each transaction category (see the ‘Transactions included in a block’ section above). Then, the network determines a gas price for each era based on the previous era's load. This price works as a multiplier for the consumed gas and relates to the gas price tolerance specified in the transaction. The transaction won't be processed if the tolerance is lower than the gas price. The gas consumed in a transaction must always be lower than the limit, or it will fail with an out-of-gas error. Finally, the cost in the no-fee model is the limit multiplied by the gas price. ### Execution results -The `ExecutionResult` class is a versioned object. Deploys processed before Condor upgrade are stored in the global -state as `ExecutionResultV1`records. And deploys and transactions processed after Condor upgrade are stored -as `ExecutionResultV2` records. +The `ExecutionResult` class is a versioned object. Deploys processed before the Condor upgrade are stored in the global state as `ExecutionResultV1`records, and deploys and transactions processed after the Condor upgrade are stored as `ExecutionResultV2` records. -The `GetTransaction` method always returns a `ExecutionResult` instance regardless the version. It has the same fields -than `ExecutionResultV2`. The user can obtain the original structure with casting this instance to the correct version: +For a processed transaction, the `GetTransaction` method always returns an `ExecutionResult` instance regardless of the version. It has the same fields as `ExecutionResultV2`. The user can obtain the original structure by casting this instance to the correct version: ```csharp if (executionResult.Version == 2) { @@ -221,41 +169,31 @@ if (executionResult.Version == 2) { } ``` -The `Effect` property contains a list of `Transforms` that modify the global state. Note that the `ExecutionEffect` -which contained also a list of operations in addition to the transforms has been removed in Condor execution results. +The Effect property contains a list of Transforms that modify the global state due to the transaction execution. Note that the ExecutionEffect type in Casper v1.x, which also contained a list of operations in addition to the transforms, has been removed in Condor execution results. ## Auction contract -The auction contract also has changed in Condor. If your application tracks validator bids, rewards and delegators, -you'll need to rework the way network responses are parsed and interpreted. A complete description of the changes cannot -covered in this guide. +The auction contract also has changed in Condor. If your application tracks validator bids, rewards, and delegators, you must rework how network responses are parsed and interpreted. A complete description of the changes cannot covered in this guide. ## Server Sent Events -The `ServerEventsClient` class can listen to both an event stream from a `v1.x` node as well as from `v2.x`. +The ServerEventsClient class can listen to an event stream from a v1.x node and from v2.x. ### Blocks -`BlockedAdded` event contains a `Block` object. When needed, the original block structure `BlockV1` or `BlockV2` can be -obtained with cast operator as described above. +The BlockedAdded event contains a Block object. The original block structure, BlockV1 or BlockV2, can be obtained with the cast operator, as described above. ### Transactions -On Condor, the events `DeployAccepted`, `DeployProcessed` and `DeployExpired` are replaced with the -equivalent `TransactionAccepted`, `TransactionProcessed` and `TransactionExpired`. These new events are emitted for -both `Deploy` and `TransactionV1` types of transactions. - -A `TransactionAccepted` event contains a `Transaction` property with either a `Deploy` or a `TransactionV1`. +On Condor, the `DeployAccepted`, `DeployProcessed`, and `DeployExpired` events are replaced with the equivalent `TransactionAccepted`, `TransactionProcessed`, and `TransactionExpired` events. These are emitted for both `Deploy` and `TransactionV1` types of transactions. -`TransactionProcessed` and `TransactionExpired` events contain a `TransactionHash` property with either a deploy hash or -a transaction version 1 hash. +A `TransactionAccepted` event contains a `Transaction` property with either a `Deploy` or a `TransactionV1`. `TransactionProcessed` and `TransactionExpired` events contain a `TransactionHash` property with either a deploy hash or a transaction version 1 hash. ### Finality signatures -The `FinalitySignature` event contains an instance of the versioned `FinalitySignature` class. Version 2 of this type is -an extension that contains all properties in version 1 plus the block height and the chain name hash. +The `FinalitySignature` event contains an instance of the versioned `FinalitySignature` class. Version 2 of this type is an extension that contains all properties in version 1 plus the block height and the chain name hash. -The user can obtain the original structure with casting this instance to the correct version: +The user can obtain the original structure by casting this instance to the correct version: ```csharp if (finalitySignature.Version == 2) { @@ -271,13 +209,11 @@ if (finalitySignature.Version == 2) { ### Last switch block hash -For a Condor network, it is possible to get the latest switch block hash with the `GetNodeStatus` method. The response -contains the `LatestSwitchBlockHash` property with this value. +For a Condor network, the `GetNodeStatus` method can be used to get the latest switch block hash. The response contains the `LatestSwitchBlockHash` property with this value. -Also, for blocks produced in Casper 2.0, the `Block` instance contains the previous switch block hash in -the `LastSwitchBlockHash` property. +Also, for blocks produced in Casper 2.0, the `Block` instance contains the previous switch block hash in the `LastSwitchBlockHash` property. ### Checksums (CEP-57) -On SDK v3 only public keys are checksummed. The rest of keys and hashes are not checksummed anymore. +On SDK v3 only public keys are checksummed with the CEP-57 standard. The rest of the keys and hashes are not checksummed anymore. From 205f95c84e5d2403b184f8263c346e524f226c85 Mon Sep 17 00:00:00 2001 From: David Hernando Date: Wed, 10 Jul 2024 10:26:55 +0200 Subject: [PATCH 6/7] Added info about versioned Transfer class to migration guide. Signed-off-by: David Hernando --- Docs/Articles/CondorMigrationGuide.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/Docs/Articles/CondorMigrationGuide.md b/Docs/Articles/CondorMigrationGuide.md index a86cc2b..e2a904e 100644 --- a/Docs/Articles/CondorMigrationGuide.md +++ b/Docs/Articles/CondorMigrationGuide.md @@ -95,6 +95,24 @@ The category, version (either a legacy Deploy or the new TransactionV1 type), an The type to represent block height is now `ulong` everywhere. `int` was used in some methods or types in the previous version. That's not the case with Casper .NET SDK v3. +## Transfers + +The response in `GetBlockTransfers()` method contains a list of `Transfer` objects. This is also a versioned object. It contains all the information related to the information. + +If you need to recover the original format, cast an instance to a `TransferV1` or `TransferV2` object: + +```csharp +var response = await rpcClient.GetBlockTransfers(); +var result = response.Parse(); +foreach(var transfer in result.Transfers) +{ + if (transfer.Version == 1) { + var transferv1 = (TransferV1)transfer; + // ... + } +} +``` + ## Account/Contract Merge On Condor, accounts and contracts are stored with the new type AddressableEntity. The EntityKind property in this type permits knowing whether the record is an Account, a stored SmartContract, or a System contract. From 8ce1bba93c5908b30e52513e47741fd188faafb9 Mon Sep 17 00:00:00 2001 From: David Hernando Date: Wed, 10 Jul 2024 12:04:42 +0200 Subject: [PATCH 7/7] Added changelog for v3.0.0-beta1. Added info about changes in GetDeploy() response. Signed-off-by: David Hernando --- CHANGELOG.md | 49 +++++++++++++++++++++++++++ Docs/Articles/CondorMigrationGuide.md | 7 +++- 2 files changed, 55 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 190db34..1426f68 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,54 @@ All notable changes to this project will be documented in this file. The format [comment]: <> (Fixed: any bug fixes) [comment]: <> (Security: in case of vulnerabilities) +## [3.0.0-beta1] + +This version is compatible with Casper node v2.0.0-rc3 and Casper node v1.5.6. + +### Added + +* New `GetEntity()` method added to the RPC client. +* New `QueryBalanceDetails()` method added to the RPC client. +* New `PutTransaction()` and `GetTransaction()` methods added to the RPC client. +* New `TransactionV1` class to model the new type of transactions in Condor. +* New global state keys added to the SDK: `AddressableEntityKey`, `BalanceHoldKey`, `BidAddrKey`, `BlockGlobalAddrKey`, `ByteCodeKey`, `EntryPointKey`, `MessageKey`, `NamedKeyKey` and `PackageKey`. +* New `AddressableEntity` class added. It may represent an account, a stored smart contract, or a system smart contract. +* New properties in the `StoredValue` class that can be retrieved with `QueryGlobalState()` method: `BidKind`, `Unbonding`, `AddressableEntity`, `Package`, `ByteCode`, `MessageTopicSummary`, `Message`, `NamedKey`, `Reservation`, and `EntryPoint`. +* New classes to represent data from the global state: `BidKind`, `UnbondingPurse`, `Package` and `ByteCode`. +* New `Message` class to contain data for native events included in the `TransactionAccepted` event from the SSE channel. +* Added `TransactionAccepted`, `TransactionProcessed`, and `TransactionExpired` events to the list of events emitted by a node through the SSE interface. + +### Changed + +* The `Block` class has changed to abstract the developer from the versioned block records returned from the network in Condor version. Refer to the migration guide for more information. +* For blocks produced in Casper 2.0, the `Block` instance contains the previous switch block hash in the `LastSwitchBlockHash` property. +* Ther `EraEnd` class has changed to abstract the developer from the versioned records returned from the network. More info in the migration guide. +* The `Transfer` class contained in the response for a `GetBlockTransfers()` call or in a `ExecutionResult` object has changed to abstract from the versioned transfer records returned from the network. Refer to the migration guide for more information. +* The input argument for the `QueryBalance()` method in the RPC client is any object from a class implementing the `IPurseIdentifier` interface. `PublicKey`, `AccountHashKey`, `URef`, and `AddressableEntity` classes implement this interface. +* The type to refer to block heights is now `ulong` across all the SDK. In previous version there was a mix of `ulong` and `int`. +* When using the `GetNodeStatus()` method with a Casper 2.0 node, the response contains the hash for the latest switch block in the `LatestSwitchBlockHash` property. +* `GetDeploy()` response has changed and now contains a `ExecutionInfo`object when the deploy has been processed instead a list of `ExecutionResult` objects. The execution info itself contains block information and a result object. +* Starting with this version of the SDK, only public keys are checksummed with the CEP-57 standard. The rest of the keys and hashes are not checksummed anymore. +* In the `StoredValue` class, `Transfer` has been renamed to `LegacyTransfer`. +* `DeployApproval` class has been renamed to `Approval` and is used for `Deploy` as well as for the new `TransactionV1` model. +* `ActionThresholds` class has now new `UpgradeManagement` property. +* The `EntryPoint` class has new entry point types and a new property `EntryPointPayment`. Both apply when working with Casper 2.0 only. +* `Step` event from SSE contains a list of `Transform` objects instead of a `ExecutionEffect` instance. +* `FinalitySignature` event contains `BlockHeight` and `ChainNameHash` value when connected to a Casper 2.0 node. +* `DeployProcessed` event from SSE contains a `ExecutionResultV1` object instead of a `ExecutionResult` object. + +### Deprecated + +* `Proposer.isSystem` property is marked as Obsolete. Use `IsSystem` with capital `I` instead. + +### Removed + +* `GetAccountBalance()` method in the RPC client has been removed. Use `QueryBalance()` instead. `GetBalance()` method exists to use `state_get_balance` from the RPC interface if needed. + +### Security + +* BouncyCastle package updated to 2.4.0 version. + ## [2.3.0] ### Added @@ -83,6 +131,7 @@ This new type permits to parse correctly the value `"00"` used for system blocks ### Added * Initial release of Casper .NET SDK. +[3.0.0-beta1]: https://github.com/make-software/casper-net-sdk/releases/tag/v3.0.0-beta1 [2.3.0]: https://github.com/make-software/casper-net-sdk/releases/tag/v2.3.0 [2.2.0]: https://github.com/make-software/casper-net-sdk/releases/tag/v2.2.0 [2.1.0]: https://github.com/make-software/casper-net-sdk/releases/tag/v2.1.0 diff --git a/Docs/Articles/CondorMigrationGuide.md b/Docs/Articles/CondorMigrationGuide.md index e2a904e..b136a39 100644 --- a/Docs/Articles/CondorMigrationGuide.md +++ b/Docs/Articles/CondorMigrationGuide.md @@ -97,7 +97,7 @@ version. That's not the case with Casper .NET SDK v3. ## Transfers -The response in `GetBlockTransfers()` method contains a list of `Transfer` objects. This is also a versioned object. It contains all the information related to the information. +The `Transfer` class contained in the response for a `GetBlockTransfers()` call or in a `ExecutionResult` object is also a versioned object. It contains all the information related to the transfer. If you need to recover the original format, cast an instance to a `TransferV1` or `TransferV2` object: @@ -161,6 +161,11 @@ Similar to the `DeployTemplates` class, which provides deploy templates for most Use the new method `PutTransaction` to send a `TransactionV1` to the network. Use the new `GetTransaction` method to retrieve an accepted transaction. Both methods can also be used to send and retrieve a Deploy. For unprocessed transactions, the ExecutionInfo in the response is `null`. Upon processing, this property contains all information about the execution, including cost, payments, errors (if any), and execution effects. + +### GetDeploy() + +Response from the `GetDeploy()` method has changed. Instead of a list of `ExecutionResult` objects, it now returns an instance of `ExecutionInfo` for a processed deploy. This instance contains block information and a results object. + ### Payments and costs For a transaction (old and new versions) processed in Condor, the execution results object contains three properties related to the gas consumed and the CSPR tokens paid: