diff --git a/src/omnicore/doc/release-notes.md b/src/omnicore/doc/release-notes.md index 02ee9fb6f68d9..cbf3533a2936d 100644 --- a/src/omnicore/doc/release-notes.md +++ b/src/omnicore/doc/release-notes.md @@ -1,9 +1,13 @@ -Omni Core v0.5.0 +Omni Core v0.6.0 ================ -v0.5.0 is a major release and consensus critical in terms of the Omni Layer protocol rules. An upgrade is mandatory, and highly recommended. Prior releases may not be compatible with new behaviour in this release. +v0.6.0 is a major release and changes the code base of Omni Core from Bitcoin Core 0.13.2 to Bitcoin Core 0.18.1. No Omni Layer consensus rules were changed and the consensus behavior of this version is identidcal with Omni Core v0.5.0. An upgrade is **not required**, but recommended in an experimental environment. -**Note: the first time you run this version, all Omni Layer transactions are reprocessed due to an database update, which may take 30 minutes up to several hours.** +**Due to the upgrade from Bitcoin Core 0.13.2 to 0.18.1, this version incooperates many changes, so please take your time to read through all release notes carefully. The first time you run this version, all the database is reconstructed, which can easily consume several hours.** + +To avoid downtime of your system, running both versions on two instances is recommended and once v0.6.0 is up-to-date and it's behavior was confirmed to work, a hot swap may be done. + +**There is no harm in skipping this version, as it's consensus behavior is identical to Omni Core v0.5.0. If you are running v0.5.0, there is no need for an update.** Please report bugs using the issue tracker on GitHub: @@ -13,15 +17,18 @@ Please report bugs using the issue tracker on GitHub: Table of contents ================= -- [Omni Core v0.5.0](#omni-core-v050) +- [Omni Core v0.6.0](#omni-core-v050) - [Upgrading and downgrading](#upgrading-and-downgrading) - [How to upgrade](#how-to-upgrade) - [Downgrading](#downgrading) - [Compatibility with Bitcoin Core](#compatibility-with-bitcoin-core) -- [Notable changes](#notable-changes) - - [Fix startup issue of Omni Core](#fix-startup-issue-of-omni-core) - - [Speed up RPC omni_listpendingtransactions](#speed-up-rpc-omni_listpendingtransactions) - - [Rename OMNI and TOMNI to OMN and TOMN](#rename-omni-and-tomni-to-omn-and-tomn) +- [Imported changes and notes](#imported-changes-and-notes) + - [Upgrade to Bitcoin Core 0.18.2](#upgrade-to-bitcoin-core-0182) + - [getinfo deprecated](#getinfo-deprecated) + - [Fee estimation improvements](#fee-estimation-improvements) + - [Transaction index changes](#transaction-index-changes) + - [rpcallowip option changes](#rpcallowip-option-changes) + - [label and account APIs for wallet](#label-and-account-apis-for-wallet) - [Change log](#change-log) - [Credits](#credits) @@ -34,57 +41,164 @@ How to upgrade If you are running Bitcoin Core or an older version of Omni Core, shut it down. Wait until it has completely shut down, then copy the new version of `omnicored`, `omnicore-cli` and `omnicore-qt`. On Microsoft Windows the setup routine can be used to automate these steps. +When upgrading from an older version, the database is reconstructed, which can easily consume several hours. + During the first startup historical Omni transactions are reprocessed and Omni Core will not be usable for approximately 15 minutes up to two hours. The progress of the initial scan is reported on the console, the GUI and written to the `debug.log`. The scan may be interrupted, but can not be resumed, and then needs to start from the beginning. Downgrading ----------- -Downgrading to an Omni Core version prior to 0.4.0 is generally not advised as older versions may not provide accurate information due to the changes in consensus rules. +Downgrading to an Omni Core version prior to 0.6.0 is not supported. Compatibility with Bitcoin Core ------------------------------- -Omni Core is based on Bitcoin Core 0.13.2 and can be used as replacement for Bitcoin Core. Switching between Omni Core and Bitcoin Core may be supported. +Omni Core is based on Bitcoin Core 0.18.2 and can be used as replacement for Bitcoin Core. Switching between Omni Core and Bitcoin Core may be supported. -Upgrading to a higher Bitcoin Core version is generally supported, but when downgrading from Bitcoin Core 0.15, Omni Core needs to be started with `-reindex-chainstate` flag, to rebuild the chainstate data structures in a compatible format. +However, it is not advised to upgrade or downgrade to versions other than Bitcoin Core 0.18. When switching to Omni Core, it may be necessary to reprocess Omni Layer transactions. -Downgrading to a Bitcoin Core version prior to 0.12 may not be supported due to the obfuscation of the blockchain database. In this case the database also needs to be rebuilt by starting Omni Core with `-reindex-chainstate` flag. -Downgrading to a Bitcoin Core version prior to 0.10 is not supported due to the new headers-first synchronization. +Imported changes and notes +========================== - -Notable changes -=============== - -Fix startup issue of Omni Core +Upgrade to Bitcoin Core 0.18.2 ------------------------------ -During startup, when reloading the effect of freeze transactions, it is checked, whether the sender of a freeze transaction is the issuer of that token and thus allowed to freeze tokens. However, if the issuer of the token has been changed in the meantime, that check fails. Such a fail is interpreted as state inconsistency, which is critical and causes a shutdown of the client. - -With this change, historical issuers are persisted and can be accessed for any given block. When there is an issuer check, it now checks against the issuer at that point, resolving the startup issue. - -Please note: the internal database of Omni Core is upgraded, which triggers a reparse of Omni Layer transactions the first time this version is started. This can take between 30 minutes and a few hours of processing time, during which Omni Core is unusable! - -Speed up RPC "omni_listpendingtransactions" -------------------------------------------- - -When adding a transaction to the mempool, a quick and unsafe check for any Omni Layer markers is done without checking transaction validity or whether it's malformed, to identify potential Omni Layer transactions. +The underlying base of Omni Core was upgraded from Bitcoin Core 0.13.2 to Bitcoin Core 0.18.2. + +Please read the following release notes for further details very carefully: + +- [Release notes for Bitcoin Core 0.14.0](https://github.com/bitcoin/bitcoin/blob/v0.18.1/doc/release-notes/release-notes-0.14.0.md) +- [Release notes for Bitcoin Core 0.14.1](https://github.com/bitcoin/bitcoin/blob/v0.18.1/doc/release-notes/release-notes-0.14.1.md) +- [Release notes for Bitcoin Core 0.14.2](https://github.com/bitcoin/bitcoin/blob/v0.18.1/doc/release-notes/release-notes-0.14.2.md) +- [Release notes for Bitcoin Core 0.14.3](https://github.com/bitcoin/bitcoin/blob/v0.18.1/doc/release-notes/release-notes-0.14.3.md) +- [Release notes for Bitcoin Core 0.15.0](https://github.com/bitcoin/bitcoin/blob/v0.18.1/doc/release-notes/release-notes-0.15.0.md) +- [Release notes for Bitcoin Core 0.15.0.1](https://github.com/bitcoin/bitcoin/blob/v0.18.1/doc/release-notes/release-notes-0.15.0.1.md) +- [Release notes for Bitcoin Core 0.15.1](https://github.com/bitcoin/bitcoin/blob/v0.18.1/doc/release-notes/release-notes-0.15.1.md) +- [Release notes for Bitcoin Core 0.15.2](https://github.com/bitcoin/bitcoin/blob/v0.18.1/doc/release-notes/release-notes-0.15.2.md) +- [Release notes for Bitcoin Core 0.16.0](https://github.com/bitcoin/bitcoin/blob/v0.18.1/doc/release-notes/release-notes-0.16.0.md) +- [Release notes for Bitcoin Core 0.16.1](https://github.com/bitcoin/bitcoin/blob/v0.18.1/doc/release-notes/release-notes-0.16.1.md) +- [Release notes for Bitcoin Core 0.16.2](https://github.com/bitcoin/bitcoin/blob/v0.18.1/doc/release-notes/release-notes-0.16.2.md) +- [Release notes for Bitcoin Core 0.16.3](https://github.com/bitcoin/bitcoin/blob/v0.18.1/doc/release-notes/release-notes-0.16.3.md) +- [Release notes for Bitcoin Core 0.17.0](https://github.com/bitcoin/bitcoin/blob/v0.18.1/doc/release-notes/release-notes-0.17.0.md) +- [Release notes for Bitcoin Core 0.17.0.1](https://github.com/bitcoin/bitcoin/blob/v0.18.1/doc/release-notes/release-notes-0.17.0.1.md) +- [Release notes for Bitcoin Core 0.17.1](https://github.com/bitcoin/bitcoin/blob/v0.18.1/doc/release-notes/release-notes-0.17.1.md) +- [Release notes for Bitcoin Core 0.18.0](https://github.com/bitcoin/bitcoin/blob/v0.18.0/doc/release-notes.md) +- [Release notes for Bitcoin Core 0.18.1](https://github.com/bitcoin/bitcoin/blob/v0.18.1/doc/release-notes.md) + + +`getinfo` deprecated +-------------------- + +The `getinfo` RPC has been deprecated. Each field in the RPC +has been moved to another commands output with that command also giving +additional information that `getinfo` did not provide. The following table +shows where each field has been moved to: + +|`getinfo` field | Moved to | +|------------------|-------------------------------------------| +`"version"` | `getnetworkinfo()["version"]` +`"protocolversion"`| `getnetworkinfo()["protocolversion"]` +`"walletversion"` | `getwalletinfo()["walletversion"]` +`"balance"` | `getwalletinfo()["balance"]` +`"blocks"` | `getblockchaininfo()["blocks"]` +`"timeoffset"` | `getnetworkinfo()["timeoffset"]` +`"connections"` | `getnetworkinfo()["connections"]` +`"proxy"` | `getnetworkinfo()["networks"][0]["proxy"]` +`"difficulty"` | `getblockchaininfo()["difficulty"]` +`"testnet"` | `getblockchaininfo()["chain"] == "test"` +`"keypoololdest"` | `getwalletinfo()["keypoololdest"]` +`"keypoolsize"` | `getwalletinfo()["keypoolsize"]` +`"unlocked_until"` | `getwalletinfo()["unlocked_until"]` +`"paytxfee"` | `getwalletinfo()["paytxfee"]` +`"relayfee"` | `getnetworkinfo()["relayfee"]` +`"errors"` | `getnetworkinfo()["warnings"]` + + +Fee estimation improvements +--------------------------- + +Fee estimation has been significantly improved with Bitcoin Core 0.15, with more accurate fee estimates used by the wallet and a wider range of options for advanced users of the `estimatesmartfee` and `estimaterawfee` RPCs (See [PR 10199](https://github.com/bitcoin/bitcoin/pull/10199)). + +### Changes to internal logic and wallet behavior + +- Internally, estimates are now tracked on three different time horizons. This allows for longer targets and means estimates adjust more quickly to changes in conditions. +- Estimates can now be *conservative* or *economical*. *Conservative* estimates use longer time horizons to produce an estimate which is less susceptible to rapid changes in fee conditions. *Economical* estimates use shorter time horizons and will be more affected by short-term changes in fee conditions. Economical estimates may be considerably lower during periods of low transaction activity (for example over weekends), but may result in transactions being unconfirmed if prevailing fees increase rapidly. +- By default, the wallet will use conservative fee estimates to increase the reliability of transactions being confirmed within the desired target. For transactions that are marked as replaceable, the wallet will use an economical estimate by default, since the fee can be 'bumped' if the fee conditions change rapidly (See [PR 10589](https://github.com/bitcoin/bitcoin/pull/10589)). +- Estimates can now be made for confirmation targets up to 1008 blocks (one week). +- More data on historical fee rates is stored, leading to more precise fee estimates. +- Transactions which leave the mempool due to eviction or other non-confirmed reasons are now taken into account by the fee estimation logic, leading to more accurate fee estimates. +- The fee estimation logic will make sure enough data has been gathered to return a meaningful estimate. If there is insufficient data, a fallback default fee is used. + +### Changes to fee estimate RPCs + +- The `estimatefee` RPC is now deprecated in favor of using only `estimatesmartfee` (which is the implementation used by the GUI) +- The `estimatesmartfee` RPC interface has been changed (See [PR 10707](https://github.com/bitcoin/bitcoin/pull/10707)): + - The `nblocks` argument has been renamed to `conf_target` (to be consistent with other RPC methods). + - An `estimate_mode` argument has been added. This argument takes one of the following strings: `CONSERVATIVE`, `ECONOMICAL` or `UNSET` (which defaults to `CONSERVATIVE`). + - The RPC return object now contains an `errors` member, which returns errors encountered during processing. + - If Bitcoin Core has not been running for long enough and has not seen enough blocks or transactions to produce an accurate fee estimation, an error will be returned (previously a value of -1 was used to indicate an error, which could be confused for a feerate). +- A new `estimaterawfee` RPC is added to provide raw fee data. External clients can query and use this data in their own fee estimation logic. + + +Transaction index changes +------------------------- + +The transaction index is now built separately from the main node procedure, +meaning the `-txindex` flag can be toggled without a full reindex. If omnicored +is run with `-txindex` on a node that is already partially or fully synced +without one, the transaction index will be built in the background and become +available once caught up. When switching from running `-txindex` to running +without the flag, the transaction index database will *not* be deleted +automatically, meaning it could be turned back on at a later time without a full +resync. + +However, please note, Omni Core requires an enabled transaction index! + +This change also has the effect that certain RPCs may not be available, until the +transaction index was fully built. + +`rpcallowip` option changes +------------------------ + +The `rpcallowip` option can no longer be used to automatically listen on all network interfaces. Instead, the `rpcbind` parameter must be used to specify the IP addresses to listen on. Listening for RPC commands over a public network connection is insecure and should be disabled, so a warning is now printed if a user selects such a configuration. If you need to expose RPC in order to use a tool like Docker, ensure you only bind RPC to your localhost, e.g. `docker run [...] -p 127.0.0.1:8332:8332` (this is an extra `:8332` over the normal Docker port specification). + + +`label` and `account` APIs for wallet +------------------------------------- -If the transaction has a potential marker, then it's added to a new cache. If the transaction is removed from the mempool, it's also removed from the cache. +A new 'label' API has been introduced for the wallet. This is intended as a +replacement for the deprecated 'account' API. The 'account' has been removed. -This speeds up the RPC "omni_listpendingtransactions" significantly, which can be used to list pending Omni Layer transactions. +The label RPC methods mirror the account functionality, with the following functional differences: -Rename OMNI and TOMNI to OMN and TOMN -------------------------------------- +- Labels can be set on any address, not just receiving addresses. This functionality was previously only available through the GUI. +- Labels can be deleted by reassigning all addresses using the `setlabel` RPC method. +- There isn't support for sending transactions _from_ a label, or for determining which label a transaction was sent from. +- Labels do not have a balance. -To be more aligned with other symbols and tickers the following changes in wording are made: +Here are the changes to RPC methods: -- "Omni", referring to the native tokens of the Omni Layer protocol, becomes "Omni tokens" -- "Test Omni", referring to the native test tokens of the Omni Layer protocol, becomes "Test Omni tokens" -- "OMNI", referring to the symbol of Omni tokens, becomes "OMN" -- "TOMNI", referring to the symbol of Test Omni tokens, becomes "TOMN" +| Deprecated Method | New Method | Notes | +| :---------------------- | :-------------------- | :-----------| +| `getaccount` | `getaddressinfo` | `getaddressinfo` returns a JSON object with address information instead of just the name of the account as a string. | +| `getaccountaddress` | n/a | There is no replacement for `getaccountaddress` since labels do not have an associated receive address. | +| `getaddressesbyaccount` | `getaddressesbylabel` | `getaddressesbylabel` returns a json object with the addresses as keys, instead of a list of strings. | +| `getreceivedbyaccount` | `getreceivedbylabel` | _no change in behavior_ | +| `listaccounts` | `listlabels` | `listlabels` does not return a balance or accept `minconf` and `watchonly` arguments. | +| `listreceivedbyaccount` | `listreceivedbylabel` | Both methods return new `label` fields, along with `account` fields for backward compatibility. | +| `move` | n/a | _no replacement_ | +| `sendfrom` | n/a | _no replacement_ | +| `setaccount` | `setlabel` | Both methods now: