Libplanet 0.11.0

Released on March 30, 2021.

Backward-incompatible API changes

• Added the parameter protocolVersion to Block<T>(long, long, BigInteger, Nonce, Address?, HashDigest<SHA256>?, DateTimeOffset, IEnumerable<Transaction<T>> transactions, HashDigest<SHA256>?, HashDigest<SHA256>?) constructor. [#1142, #1147, #1162]
• Added the parameter to protocolVersion to Block<T>.Mine() method. [#1142, #1147, #1162]
• Added the first parameter protocolVersion to BlockHeader() constructor. [#1142, #1147, #1162]
• Added stagePolicy as the second parameter to BlockChain<T>() constructor. [#1130, #1131]
• Added IBlockPolicy<T>.CanonicalChainComparer property to make the canonical chain. [#1155, #1165, #1184]
• Added canonicalChainComparer as the last parameter to BlockPolicy() constructors. [#1155, #1165, #1184]
• Added canonicalChainComparer as the second parameter to DelayedRenderer() constructor. [#1155, #1165, #1184]
• Added canonicalChainComparer as the second parameter to DelayedActionRenderer() constructor. [#1155, #1165, #1184]
• Added reorgResistantHeight parameter into DelayedActionRenderer<T>() constructor. [#1163]
• Added IStore.SetBlockPerceivedTime() method. [#1184]
• Added IStore.GetBlockPerceivedTime() method. [#1184]
• Removed TransactionSet<T> class. [#1165]
• Removed IBlockStatesStore interface. [#1117]
• Removed BaseBlockStatesStore abstract class. [#1117]
• Removed Swarm<T>.GetTrustedStateCompleterAsync() method. [#1117]
• Removed trustedStateValidators parameter from Swarm<T>.PreloadAsync() method. [#1117]
• Removed Swarm<T>.TraceTable() method. [#1120]
• Added IActionContext.BlockAction property. [#1143]
• Added nullable TimeSpan-typed messageLifespan parameter into NetMQTransport() constructor. [#1171]
• Added IStore.ForkTxNonces() method. [#1198]
• Removed PeerState.Address Property. [#1215]
• IProtocol.RebuildConnectionAsync(CancellationToken) method was replaced by, IProtocol.RebuildConnectionAsync(int, CancellationToken) method. [#1215]

Backward-incompatible network protocol changes

• Swarm<T> became no longer retry when Swarm<T> receives less than 500 blocks. [#1112]
• The existing ChainStatus message type (with the type number 0x24) was replaced by a new ChainStatus message type (with the type number 0x25). [#1155, #1165]
• Removed the message types depended on features of IBlockStatesStore interface. [#1117]
  • GetRecentStates message type (with the type number 0x0b)
  • RecentStates message type (with the type number 0x13)
  • GetBlockStates message type (with the type number 0x22)
  • BlockStates message type (with the type number 0x23)
• Swarm<T> became to ignore messages made earlier than a certain amount of time, which is configured by SwarmOptions.MessageLifespan. [#1160, #1171]

Backward-incompatible storage format changes

• (Libplanet.RocksDBStore) The blocks and transactions became stored in multiple databases. Each block and transaction belongs to a partition of the database, according to its epoch unit, which is its Unix timestamp. Every epoch is divided by certain seconds, configured by RocksDBStore() constructor's txEpochUnitSeconds and blockEpochUnitSeconds parameters (86400 by default). [#1183, #1194]
• (Libplanet.RocksDBStore) Continue on partitioning of database, RocksDBStore() is manage database connection by LRU Cache. The max size of connection cache is configured by RocksDBStore() constructor's dbConnectionCacheSize parameters (100 by default). [#1183, #1194]
• (Libplanet.RockDBStore) The RocksDBStore that was previously used has been separated into a class called MonoRocksDBStore. Please use this class if you need to migrate. [#1183, #1204]

Added APIs

• Added Block<T>.CurrentProtocolVersion constant. [#1142, #1147]
• Added Block<T>.ProtocolVersion property. [#1142, #1147]
• Added Block<T>.Header property. [#1070, #1102]
• Added BlockHeader.ProtocolVersion property. [#1142, #1147]
• Added IBlockExcerpt interface. [#1155, #1165, #1170]
• Added BlockExcerpt static class. [#1155, #1165, #1170, #1184]
• Block<T> became to implement IBlockExceprt interface. [#1155, #1165, #1170]
• BlockHeader became to implement IBlockExceprt interface. [#1155, #1165, #1170]
• Added BlockPerception struct. [#1155, #1184]
• Added BlockChain<T>.PerceiveBlock() method. [#1155, #1184]
• Added DelayedRenderer<T>.CanonicalChainComparer and DelayedActionRenderer<T>.CanonicalChainComparer properties. [#1155, #1165, #1184]
• Added TotalDifficultyComparer class. [#1155, #1165, #1170, #1184]
• Added IStagePolicy<T> interface. [#1130, #1131, #1186]
• Added VolatileStagePolicy<T> class. [#1130, #1131, #1136, #1186]
• Added ITransport interface. [#1052]
• Added NetMQTransport class which implements ITransport. [#1052]
• Added Message abstract class. [#1052]
• Added BlockExceedingTransactionsException class. [#1104, #1110]
• Added BlockChain<T>.GetStagedTransactionIds() method. [#1089]
• (Libplanet.RocksDBStore) Added maxTotalWalSize, keepLogFileNum and maxLogFileSize parameters into RocksDBStore() constructor. [#1065, #1102, #1132]
• Added Swarm<T>.BlockDemand property. [#1068, #1102]
• Added BlockDemand struct. [#1068, #1102]
• Added TurnClient.PublicAddress property. [#1074, #1102]
• Added TurnClient.EndPoint property. [#1074, #1102]
• Added TurnClient.BehindNAT property. [#1074, #1102]
• Added TurnClient.InitializeTurnAsync(int, CancellationToken) method. [#1074, #1102]
• Added TurnClient.StartAsync(int, CancellationToken) method. [#1074, #1102]
• Added TurnClient.ReconnectTurn(int, CancellationToken) method. [#1074, #1102]
• Added TurnClient.IsConnectable(CancellationToken) method. [#1074, #1102]
• Added TurnClient.ReconnectTurn(CancellationToken) method. [#1074, #1102]
• Added Libplanet.Blockchain.Renderers.Debug.RenderRecord<T> abstract class and its subclasses: [#1119]
  • RenderRecord<T>.ActionBase abstract class
  • RenderRecord<T>.ActionSuccess class
  • RenderRecord<T>.ActionError class
  • RenderRecord<T>.BlockBase abstract class
  • RenderRecord<T>.Block class
  • RenderRecord<T>.Reorg class
• Added Libplanet.Blockchain.Renderers.Debug.RecordingActionRenderer<T> class. [#1119]
• Added Libplanet.Blockchain.Renderers.Debug.ValidatingActionRenderer<T> class. [#1119]
• Added Libplanet.Blockchain.Renderers.Debug.InvalidRenderException<T> class. [#1119]
• Added InvalidBlockProtocolVersionException class. [#1142, #1147]
• Added InvalidBlockTxHashException class. [#1116]
• Added Swarm<T>.PeerStates property. [#1120]
• Added IProtocol interface. [#1120]
• Added KademliaProtocol class which implements IProtocol. [#1120, #1135]
• Added reorgResistantHeight parameters into DelayedActionRenderer<T>() constructor. [#1163]
• Added InvalidBlockPreEvaluationHashException class. [#1148]
• Added the parameter validate which is true by default, to Transaction<T>.Deserialize(). [#1149]
• Added SwarmOptions.MessageLifespan property. [#1171]
• Added InvalidTimestampException class. [#1171]
• Added PeerState.Peer Property. [#1215]
• Added SwarmOptions.RefreshPeriod property, which is 10 seconds by default. [#1215]
• Added SwarmOptions.RefreshLifespan property, which is 60 seconds by default. [#1215]

Behavioral changes

• Upgraded Bencodex package (which is a dependency) so that Libplanet gets benefits from its recent optimizations. [#1081, #1084, #1086, #1101]
• Introduced the protocol versioning scheme. This purposes to change the protocol without breaking backward compatibility. Even the protocol is changed, the existing blocks made before the new protocol are guaranteed to behave as it had done. [#1142, #1147, #1155 #1162, #1170, #1184]
• Since BlockHeader.ProtocolVersion was added, the existing blocks are considered protocol compliant with the protocol version zero. [#1142, #1147, #1162]
• When a BlockChain<T> follows VolatileStagePolicy<T>, which is Libplanet's the only built-in IStagePolicy<T> implementation at the moment, as its StagePolicy, its staged transactions are no longer persistent but volatile instead. It also automatically purges staged transactions after the given Lifetime, which is 3 hours by default. [#1130, #1131, #1136, #1186]
• Swarm<T> became not to receive states from trusted peers. [#1061, #1102]
• Swarm<T> became not to retry when block downloading. [#1062, #1102]
• Improved performance of BlockChain<T>.MineBlock(). [#1116, #1124]
• Improved performance of Block<T>.Deserialize(). [#1116]
• Swarm<T> became not to fill states from trusted peers, because now states can be validated rather than trusted due to MPT. [#1117]
• HashDigest<SHA256> became serializable. [#795, #1125]
• Transaction<T>() constructors became not to validate itself. [#1149]
• BlockChain<T>.Append() became to validate the given Block<T> before storing its StateRootHash. [#1172]
• Blockchain<T> became not to stage transactions having nonce less than or equal to the nonce of the same signer's latest transaction in already mined blocks. [#1173, #1180, #1186]
• Improved security of Message.Parse(). [#1161, #1181]
• Improved performance of BlockChain<T>.Fork(). [#1198]
• Swarm<T> became not to call KademliaProtocol.RebuildConnectionAsync() right after Swarm<T>.StartAsync(). If you called Swarm<T>.BootstrapAsync() before Swarm<T>.StartAsync(), peers in your table may not have you in their table right after Swarm<T>.StartAsync() (which was almost guaranteed before). [#1208]
• Peers added during Swarm<T>.BootstrapAsync() before Swarm<T>.StartAsync() are now marked as stale so that Swarm<T>.RefreshTableAsync() will update. [#1215]
• Following classes became to leave log messages with its class as logging context. [#1218]
  • TrieStateStore class
  • TurnClient class
  • ActionEvaluation class

Bug fixes

• Fixed a bug where BlockChain<T>.MineBlock() was not automatically cancelled when the tip of the chain was changed occasionally. [#1141]
• Fixed a bug where blocks with invalid PreEvaluationHash was considered as a valid block. [#1148, #1202]
• Fixed a vulnerability of the IAccountStateDelta.TransferAsset()'s internal implementation that it had doubled recipient's balance when a sender and a recipient is the same. *Since this changes the protocol, for backward compatibility, the actions belonging to the existing block, which was mined before the protocol v1, are guaranteed to still behave as it had done. [#1152]
• Fixed a bug where Block<T>.Evaluate() hadn't validate its hash. [#1168]
• Fixed memory leak due to undisposed CancellationTokenSources. [#1182, #1212]
• Fixed a bug where TurnClient hadn't released its relay connections after reconnecting. [#1185]

CLI tools

• planet mpt diff command became to take 4 arguments (which was 3) so that it can compare state root hashes from two different KV stores. The existing commands like planet mpt diff STORE A B do not work anymore, and these should be instead like planet mpt diff STORE A STORE B. [#1129]
• Store aliases used by planet mpt became to disallow names looking like URIs to disambiguate aliases from the literal store URIs. [#1129]
• Added new subcommands planet mpt list and planet mpt query. [#1137]