Exonum Java Light Client 0.6.0

0.6.0 — 2020-04-06

Versions Support

• Exonum 1.0
• Exonum Java Binding 0.10

Added

• Exonum 1.0.0 compatibility

Removed

• System API operations that were made private and/or removed. If you need
  any of these, use the system REST API directly.
  • getUnconfirmedTransactionsCount. stats system API endpoint is made private.
  • healthCheck. healthcheck endpoint is merged into info (and made private).
  • getUserAgentInfo. user_agent endpoint is merged into info.

Exonum Java Binding 0.10.0

Overview

The main feature of Exonum Java 0.10.0 is enhanced support of dynamic services and
their lifetime. Service instances might be stopped and resumed now. While
stopped, the service does not process transactions and its API endpoints are
unavailable.

Most of the user-facing interfaces were reworked to facilitate access to the
database and transaction execution context, and more distinction between
storage access abstractions were added to enforce services isolation.

Finally, the support of Protobuf-serialized proofs has been re-enabled and
expanded since the last release.

If you are upgrading an existing Java service, consult the migration guide. If you are new to Exonum — see the new tutorial on service development.

This release is based on Exonum 1.0.0, the first
stable Exonum release. See release notes for details.

Added

• Support of creation of various blockchain proofs:

  • Block Proof
  • Transaction Execution Proof
  • Call Result Proof
  • Service Data Proof.

  See Blockchain BlockProof and IndexProof
  for details. (#1355)

  • Proofs for executing service can be created with
    BlockchainData#createIndexProof directly by the index simple name.

• Support of creation of Protobuf-based proofs for maps and lists.
  Such proofs can be easily serialized using Protocol Buffers
  and sent to the light clients.
  See:

  • ProofMapIndexProxy#getProof and MapProof;
  • ProofListIndexProxy.getProof, ProofListIndexProxy.getRangeProof and
    ListProof;
  • Blockchain.

• ProofEntryIndex collection and EntryIndex interface.

  • EntryIndex#orElse method.

• Execution preconditions utility methods,
  see com.exonum.binding.core.service.ExecutionPreconditions. (#1351)

• supervisor-mode CLI parameter added for generate-template command. It
  allows to configure the mode of the Supervisor service. Possible values are
  "simple" and "decentralized". (#1361)

• Support of service instances lifecycle: they can be activated, stopped and resumed now.
  Also, service instance artifacts can be upgraded before resuming which allows services
  API update, add new service transactions, synchronous data migration etc. (#1358, #1372)

• BlockchainData — an object providing access to all categories of persistent data
  stored in the database: the executing service data, other services’ data,
  Exonum Core data. BlockchainData is a service-specific object — it remembers
  the service to which it is provided and allows modification only to the data
  of that service. The service data is automatically isolated via namespaces,
  with a service name followed by a dot as a prefix
  (see BlockchainData#getExecutingServiceData). (#1393)

• Prefixed and ReadonlyFork database Accesses. (#1382, #1385)

• Service#beforeTransactions.

• KeyPair#newInstance(PrivateKey, PublicKey)

• Blockchain#getNumTransactions, returning the total number of committed
  to the blockchain transactions.

• Blockchain#getNextHeight, returning the height of the next committed block.

• Configuration can be passed in several text-based formats: JSON, Java
  properties, plain text.
  The configuration parameters are transferred using a standard protobuf message
  ServiceConfiguration.
  exonum-launcher comes with built-in support for text-based configuration
  formats.

Changed

• Transactions are now implemented as service methods annotated with
  @Transaction(TX_ID), instead of classes implementing
  Transaction interface. (#1274, #1307)
• Any exceptions thrown from the Transaction methods
  but ExecutionException are saved with the error kind
  "unexpected" into Blockchain#getCallErrors.
• Redefined TransactionExecutionException:
  • Renamed into ExecutionException and moved to package
    com.exonum.binding.core.service
  • Made TransactionExecutionException an unchecked (runtime) exception
  • Specified it as the exception to communicate execution errors
    of Service methods: @Transactions; Service#afterTransactions,
    #initialize; Configurable methods.
• Similarly, redefined TransactionContext:
  • Renamed into ExecutionContext and moved to package
    com.exonum.binding.core.service
  • Replaced BlockchainData argument in transaction-like Service and
    Configurable methods with ExecutionContext. The BlockchainData
    remains accessible via TransactionContext#getBlockchainData,
    and service data via TransactionContext#getServiceData.
  • Made getTransactionMessageHash return Optional<HashCode;
    and getAuthorPk return Optional<PublicKey> because the context
    is also used for non-transaction methods. (#1462)
• Renamed Service#beforeCommit into Service#afterTransactions.
• Allowed throwing execution exceptions from Service#afterTransactions
  (ex. beforeCommit).
  Any exceptions thrown in these methods are saved in the blockchain
  in Blockchain#getCallErrors and can be retrieved by any services or
  light clients.
• Blockchain#getTxResults is replaced by Blockchain#getCallErrors.
  • Use CallInBlocks to concisely create CallInBlocks.
• The specification of Configurable operations and Service#initialize
  to require throwing ExecutionException instead of
  IllegalArgumentException.
• Transaction index in block type changed from long to int. (#1348)
• Extracted artifact version to the separate field from the artifact name.
  Artifact name format is groupId/artifactId now.
  PluginId format is runtimeId:artifactName:artifactVersion now. (#1349)
• Extracted #getIndexHash into HashableIndex interface. (#1366)
• Made Views (Fork and Snapshot) index factories. An index factory
  implements Access interface. Access allows instantiating various
  MerkleDB indexes, aka "collections" (e.g., Access#getList -> ListIndex).
  Access methods must be used to create indexes in service code.
  Factory methods in indexes must no longer be used (see also 'Removed'
  section below).
  • Use Access instead of View (which is renamed to AbstractAccess).
  • IndexAddresses are resolved relatively to Accesses (#1374)
• Exonum protobuf messages are moved from exonum-java-binding-common
  to a new module com.exonum.messages:exonum-messages.
• Java 11 is the minimum required version to run Exonum services.
  Client libraries: exonum-messages and exonum-java-binding-common remain
  Java 8 compatible.
• The service archetype to produce a multi-module service template project,
  with a separate module for Protocol Buffers messages, so that they
  can be re-used in light clients; and a module for service code. (#1461)
• ServiceArtifactId and RuntimeId are moved to
  com.exonum.binding.common.runtime package. (#1452)
• Renamed the KeyPair factory methods to newInstance.

Removed

• Classes supporting no longer used tree-like list proof representation.
• Schema#getStateHashes and Service#getStateHashes methods. Framework
  automatically aggregates state hashes of the Merkelized collections.
• TransactionConverter — it is no longer needed with transactions
  as Service methods annotated with @Transaction. Such methods may accept
  arbitrary protobuf messages as their argument. (#1304, #1307)
• ExecutionStatuses factory methods (serviceError) as they are no longer
  useful to create expected transaction execution statuses in tests —
  an ExecutionError now has a lot of other properties.
  ExecutionStatuses.success is replaced with ExecutionStatuses.SUCCESS constant.
• newInstance methods in all the indexes are made internal:
  • Use Access methods instead. E.g., instead of ProofListIndexProxy.newInstance
    use Access.getProofList.
  • Instead of using overloads accepting protobuf classes, create a serializer
    explicitly with StandardSerializers.protobuf.
  • To create index groups (aka families), pass a group address:
    IndexAddress.valueOf(String, byte[]). (#1374)
• AbstractService#createDataSchema — just use the schema constructor/factory
  method, as passing the instance name is no longer required with the Prefixed
  DB Access. (#1393)

Known Issues

• Java 14 is not supported as the runtime for Exonum Java services — see #1509.
  JDK 11 through 13 work fine.

Exonum Java Light Client 0.5.0

The new release of the light client brings support for dynamic services.

Versions Support

• Exonum version, 0.13
• Exonum Java Binding version, 0.9

Added

• Java 13 support.
• ExonumClient#findServiceInfo(String) to retrieve a service id by its
  name and ExonumClient#getServiceInfoList to retrieve the list of all
  started services - their names and ids. (#1247)

Changed

• TransactionResponse#getExecutionResult now returns ExecutionStatus
  instead of TransactionResult. (#1244)

Exonum Java Binding 0.9.0-rc2

This is a bug-fix release, see 0.9.0-rc1 changelog for information on the changes in 0.9.0.

Fixed

• Published on Maven Central a missing dependency of a Testkit module
  (exonum-java-app). (#1297)

Exonum Java Binding 0.9.0-rc1

Overview

The main feature of this release is support for dynamic services. Dynamic services can be added
to the blockchain network after it has been started. Since this release EJB also supports multiple
instances of the same service.
Creating proofs is not supported in this release. They will be re-enabled in one of the following
releases.

This release is based on Exonum 0.13.0-rc.2.

If you are upgrading an existing Java service, consult the migration guide.

Added

• Dynamic services support. (#1065, #1145, #1183)
• Exonum protobuf messages to common module. (#1085)
• Service#beforeCommit handler. (#1132)
• TestKit support for dynamic services. (#1145)
• Support for flat list proofs, the new compact proof format for ProofList. Not introduced to
  ProofListIndexProxy for now. (#1156)
• Java runtime plugin for exonum-launcher. (#1171)
• serviceName and serviceId were added to TransactionContext. They are used for creating
  schemas with unique namespaces. (#1181)
• Implement run-dev command support for running the node in development mode. (#1217)
• Configurable interface corresponding to exonum.Configure. (#1234)
• ProofMapIndexProxy#truncate and #removeLast. (#1272)
• Java 13 support.

Changed

• Support for the new protobuf-based TransactionMessage format is provided. (#1085)
• TimeSchema supports multiple time service instances. (#1136)
• TransactionResult is replaced with ExecutionStatus. (#1174)
• MapProof enforces 32-byte long hash codes. (#1191)
• The default ProofMapIndexProxy implementation has been changed to hash user keys to produce an
  internal key. The implementation that does not hash the keys is still supported, see
  documentation. (#1222)
• Updated Exonum to 0.13.0-rc.2 — see Exonum release page
  for details.

Removed

• Service#getId and Service#getName are removed. AbstractService now provides
  similar methods that can be used as replacements. (#1065)
• Blockchain#getActualConfiguration has been replaced with
  Blockchain#getConsensusConfiguration, returning only the consensus configuration (now also
  containing the validator public keys) as a Protobuf message. (#1185)
• Transaction#info method is removed as it is no longer used by the framework. (#1225)
• ProofMapIndexProxy#getProof and ProofListIndexProxy#getProof are disabled in this release.

Known Issues

• exonum-java-app module, required by testkit, is not deployed to Maven Central.
  That is resolved in master and ejb/v0.9.0-rc2 and will be released soon as "0.9.0-rc2" (#1297)

Exonum Java Light Client 0.4.0

The new release of the light client brings support for Exonum 0.12
and Exonum Java 0.8.

Versions Support

• Exonum 0.12.*
• Exonum Java 0.8.*

Changed

• ExonumClient#getBlockByHeight and #getBlocks to throw
  IllegalArgumentException when blocks with heights exceeding
  the current blockchain height are requested (#1137)
• Block JSON representation to be compatible with the one used
  for blocks by the core. Applied @SerializedName annotation
  to all fields. (#1137)
• Updated project dependencies to the newest versions.

Exonum Java Binding v0.8.0

This release brings mainly internal fixes and improvements. It is based on Exonum 0.12.

Changed

• Ed25519CryptoFunction to use the system libsodium by default. If libsodium is not installed,
  it will load the bundled library. (#991)
• Ed25519CryptoFunction is made package-private. It remains accessible via
  CryptoFunctions#ed25519.
• After the introduction of MerkleDB the hash of the index is not equal to the root hash of the
  corresponding proof tree anymore. Therefore CheckedProof#getRootHash,
  ProofListIndexProxy#getRootHash and ProofMapIndexProxy#getRootHash are replaced with
  CheckedProof#getIndexHash, ProofListIndexProxy#getIndexHash and
  ProofMapIndexProxy#getIndexHash accordingly.
• Network configuration workflow. generate-config subcommand now accepts a single parameter -
  output directory instead of separate parameters for private and public node configs. See
  Tutorial for updated instructions.

Added

• stream for sets: KeySetIndex and ValueSetIndex. (#1088)
• Proofs of absence of an element with the specified index for ProofListIndexProxy. (#1081)

Exonum Light Client 0.3.0

The third release of Exonum Java Light Client which improves convenience in working with blocks and allows specifying a custom path prefix to Exonum API.

Versions Support

• Exonum version, 0.11.0
• Exonum Java Binding version, 0.6.0-0.7.0

Added

• ExonumClient#findNonEmptyBlocks to find a certain number of the most recent non-empty
  blocks (from the last block and up to the genesis block). (#953)
• Prefix URL can be set for routing all Light Client requests. (#997)

Changed

• ExonumClient#getBlocks accepts a closed range of block heights [from; to] and returns only the blocks which heights fall into that range. The size of the range (to - from + 1) is no longer limited. If needed, the client performs multiple requests to the node. (#953)
• ExonumClient#getLastBlocks returns only the blocks from the closed range [max(0, blockchainHeight - count + 1), blockchainHeight]. The size of the range (min(count, blockchainHeight + 1)) is no longer limited. (#953)
• Now port is optional in the Exonum host URL. (#997)

Exonum Java 0.7.0

Exonum Java 0.7.0 brings support of Exonum TestKit, massive performance improvements,
and various other fixes and improvements. It is based on Exonum 0.11.

If you are upgrading an existing Java service, consult the migration guide.

Added

• A new exonum-testkit module that allows to emulate blockchain network and test transaction
  execution in the synchronous environment (that is, without consensus algorithm and network
  operation involved).
  Main component of this module is TestKit which allows recreating behavior of a single full
  node (a validator or an auditor) in an emulated Exonum blockchain network.
  For more information and examples see documentation.
  (#819, #833, #859, #913, #989)
• Verification of native library compatibility when it is first loaded, to detect
  possible mismatch between an installed exonum-java application and the version
  used in a service project. (#882)
• Block#isEmpty()
• RawTransaction#fromMessage(TransactionMessage), which is mostly useful in tests,
  where you might have a message but need it as a RawTransaction in some assertions.

Changed

• Improved the throughput of transaction processing twofold. Java services on Exonum Java 0.7.0
  handle transactions about 15–20% slower than equivalent Rust ones, according to our system
  benchmarks. (#917, #996)
• BinaryTransactionMessage#toString to include some fields in human-readable
  format instead of the whole message in binary form.
• Node#submitTransaction to throw unchecked TransactionSubmissionException instead
  of checked InternalServerError.
• Moved all packages inside com.exonum.binding to com.exonum.binding.core package.
  That was required to give each module a unique root package to prevent 'split-packages'
  problem. The migration guide has a regexp to update the service automatically.
• Replaced redundant TypeAdapterFactory in 'common' module with a single
  CommonTypeAdapterFactory. BlockTypeAdapterFactory is renamed to CoreTypeAdapterFactory.
  JsonSerializer#json and JsonSerializer#builder register CommonTypeAdapterFactory
  by default. CoreTypeAdapterFactory must be registered explicitly if needed. (#971)
• Exonum Java App now uses static linkage for RocksDB on Mac OS. Installed RocksDB
  is no more necessary to run the App. (#1011)

Fixed

• The default Transaction#info implementation causing an error on transaction
  request. It is modified to return an empty object by default (no info in content.debug field
  of the response to transaction). (#904)
• Allow to override root package in the template project generated with
  the exonum-java-binding-service-archetype. It remains equal to 'groupId' property
  by default, but can be overridden with 'package' property.
• Application packaging issue that might have resulted in several versions of Java artifacts
  on the application classpath. (#968)

Exonum Light Client 0.2.0

The second release of Exonum Java Light Client which brings
system API and blockchain explorer API endpoints support.

Versions Support

• Exonum 0.11.0
• Exonum Java Binding 0.6.0

Added

• Support of System API public endpoints. (#716)
• Support of Explorer API endpoints. (#725, #734)