Merge branch 'develop' into Error_messages

PeterChen13579 · Sep 19, 2023 · 2e42c43 · 2e42c43
2 parents ba56c77 + a948203
commit 2e42c43
Show file tree

Hide file tree

Showing 247 changed files with 68,904 additions and 8,856 deletions.
diff --git a/API-CHANGELOG.md b/API-CHANGELOG.md
@@ -1,22 +1,16 @@
 # API Changelog
 
-This changelog is intended to list all updates to the API.
+This changelog is intended to list all updates to the [public API methods](https://xrpl.org/public-api-methods.html).
 
-For info about how API versioning works, view the [XLS-22d spec](https://github.com/XRPLF/XRPL-Standards/discussions/54). For details about the implementation of API versioning, view the [implementation PR](https://github.com/XRPLF/rippled/pull/3155).
+For info about how [API versioning](https://xrpl.org/request-formatting.html#api-versioning) works, including examples, please view the [XLS-22d spec](https://github.com/XRPLF/XRPL-Standards/discussions/54). For details about the implementation of API versioning, view the [implementation PR](https://github.com/XRPLF/rippled/pull/3155). API versioning ensures existing integrations and users continue to receive existing behavior, while those that request a higher API version will experience new behavior.
 
 The API version controls the API behavior you see. This includes what properties you see in responses, what parameters you're permitted to send in requests, and so on. You specify the API version in each of your requests. When a breaking change is introduced to the `rippled` API, a new version is released. To avoid breaking your code, you should set (or increase) your version when you're ready to upgrade.
 
-For a log of breaking changes, see the **API Version [number]** headings. Breaking changes are associated with a particular API Version number. For non-breaking changes, scroll to the **XRP Ledger version [x.y.z]** headings. Non-breaking changes are associated with a particular XRP Ledger (`rippled`) release.
-
-## API Version 2
-This version will be supported by `rippled` version 1.12.
-
-#### V2 account_info response
-
-`signer_lists` is returned in the root of the response, instead of being nested under `account_data` (as it was in API version 1). ([#3770](https://github.com/XRPLF/rippled/pull/3770))
+For a log of breaking changes, see the **API Version [number]** headings. In general, breaking changes are associated with a particular API Version number. For non-breaking changes, scroll to the **XRP Ledger version [x.y.z]** headings. Non-breaking changes are associated with a particular XRP Ledger (`rippled`) release.
 
 ## API Version 1
-This version is supported by `rippled` version 1.11.
+
+This version is supported by all `rippled` versions. At time of writing, it is the default API version, used when no `api_version` is specified. When a new API version is introduced, the command line interface will default to the latest API version. The command line is intended for ad-hoc usage by humans, not programs or automated scripts. The command line is not meant for use in production code.
 
 ### Idiosyncrasies
 
@@ -30,7 +24,7 @@ The `network_id` field was added in the `server_info` response in version 1.5.0
 
 ## XRP Ledger version 1.12.0
 
-Version 1.12.0 is in development.
+[Version 1.12.0](https://github.com/XRPLF/rippled/releases/tag/1.12.0) was released on Sep 6, 2023.
 
 ### Additions in 1.12
 
@@ -76,9 +70,11 @@ Additions are intended to be non-breaking (because they are purely additive).
 
 ### Breaking changes in 1.11
 
-- Added the ability to mark amendments as obsolete. For the `feature` admin API, there is a new possible value for the `vetoed` field. ([#4291](https://github.com/XRPLF/rippled/pull/4291))
-- The API now won't accept seeds or public keys in place of account addresses. ([#4404](https://github.com/XRPLF/rippled/pull/4404))
-- For the `ledger_data` method, when all entries are filtered out, the API now returns an empty list (an empty array, `[]`). (Previously, it would return `null`.) While this is technically a breaking change, the new behavior is consistent with the documentation, so this is considered only a bug fix. ([#4398](https://github.com/XRPLF/rippled/pull/4398))
+- Added the ability to mark amendments as obsolete. For the `feature` admin API, there is a new possible value for the `vetoed` field. (https://github.com/XRPLF/rippled/pull/4291)
+  - The value of `vetoed` can now be `true`, `false`, or `"Obsolete"`.
+- Removed the acceptance of seeds or public keys in place of account addresses. (https://github.com/XRPLF/rippled/pull/4404)
+  - This simplifies the API and encourages better security practices (i.e. seeds should never be sent over the network).
+- For the `ledger_data` method, when all entries are filtered out, the `state` field of the response is now an empty list (in other words, an empty array, `[]`). (Previously, it would return `null`.) While this is technically a breaking change, the new behavior is consistent with the documentation, so this is considered only a bug fix. (https://github.com/XRPLF/rippled/pull/4398)
 - If and when the `fixNFTokenRemint` amendment activates, there will be a new AccountRoot field, `FirstNFTSequence`. This field is set to the current account sequence when the account issues their first NFT. If an account has not issued any NFTs, then the field is not set. ([#4406](https://github.com/XRPLF/rippled/pull/4406))
   - There is a new account deletion restriction: an account can only be deleted if `FirstNFTSequence` + `MintedNFTokens` + `256` is less than the current ledger sequence.
   - This is potentially a breaking change if clients have logic for determining whether an account can be deleted.
@@ -97,3 +93,51 @@ Additions are intended to be non-breaking (because they are purely additive).
 - Added an `account_flags` object to the `account_info` method response. (https://github.com/XRPLF/rippled/pull/4459)
 - Added `NFTokenPages` to the `account_objects` RPC. (https://github.com/XRPLF/rippled/pull/4352)
 - Fixed: `marker` returned from the `account_lines` command would not work on subsequent commands. (https://github.com/XRPLF/rippled/pull/4361)
+
+# In development
+
+Changes below this point are in development.
+
+## API Version 2
+
+At the time of writing, this version is expected to be introduced in `rippled` version 2.0.
+
+Currently (prior to the release of 2.0), it is available as a "beta" version, meaning it can be enabled with a config setting in `rippled.cfg`:
+```
+[beta_rpc_api]
+1
+```
+
+Since `api_version` 2 is in "beta", breaking changes can be made at any time.
+
+#### Modifications to account_info response in V2
+
+- `signer_lists` is returned in the root of the response. Previously, in API version 1, it was nested under `account_data`. (https://github.com/XRPLF/rippled/pull/3770)
+- When using an invalid `signer_lists` value, the API now returns an "invalidParams" error. (https://github.com/XRPLF/rippled/pull/4585)
+  - (`signer_lists` must be a boolean. In API version 1, strings are accepted and may return a normal response - as if `signer_lists` were `true`.)
+
+#### Modifications to [account_tx](https://xrpl.org/account_tx.html#account_tx) response in V2
+
+- Using `ledger_index_min`, `ledger_index_max`, and `ledger_index` returns `invalidParams` because if you use `ledger_index_min` or `ledger_index_max`, then it does not make sense to also specify `ledger_index`. Previously, in API version 1, no error was returned. (https://github.com/XRPLF/rippled/pull/4571)
+  - The same applies for `ledger_index_min`, `ledger_index_max`, and `ledger_hash`. (https://github.com/XRPLF/rippled/issues/4545#issuecomment-1565065579)
+- Using a `ledger_index_min` or `ledger_index_max` beyond the range of ledgers that the server has:
+  - returns `lgrIdxMalformed` in API version 2. (https://github.com/XRPLF/rippled/issues/4288)
+  - Previously, in API version 1, no error was returned.
+
+##### In progress
+
+- Attempting to use a non-boolean value (such as a string) for the `binary` or `forward` parameters returns `invalidParams` (`rpcINVALID_PARAMS`). Previously, in API version 1, no error was returned. (https://github.com/XRPLF/rippled/pull/4620)
+
+#### Modifications to [noripple_check](https://xrpl.org/noripple_check.html#noripple_check) response in V2
+
+##### In progress
+
+- Attempting to use a non-boolean value (such as a string) for the `transactions` parameter returns `invalidParams` (`rpcINVALID_PARAMS`). Previously, in API version 1, no error was returned. (https://github.com/XRPLF/rippled/pull/4620)
+
+# Unit tests for API changes
+
+The following information is useful to developers contributing to this project:
+
+The purpose of unit tests is to catch bugs and prevent regressions. In general, it often makes sense to create a test function when there is a breaking change to the API. For APIs that have changed in a new API version, the tests should be modified so that both the prior version and the new version are properly tested.
+
+To take one example: for `account_info` version 1, WebSocket and JSON-RPC behavior should be tested. The latest API version, i.e. API version 2, should be tested over WebSocket, JSON-RPC, and command line.
diff --git a/BUILD.md b/BUILD.md
@@ -1,7 +1,7 @@
-> These instructions assume you have a C++ development environment ready
-> with Git, Python, Conan, CMake, and a C++ compiler. For help setting one up
-> on Linux, macOS, or Windows, see [our guide](./docs/build/environment.md).
->
+| :warning: **WARNING** :warning:
+|---|
+| These instructions assume you have a C++ development environment ready with Git, Python, Conan, CMake, and a C++ compiler. For help setting one up on Linux, macOS, or Windows, [see this guide](./docs/build/environment.md). |
+
 > These instructions also assume a basic familiarity with Conan and CMake.
 > If you are unfamiliar with Conan,
 > you can read our [crash course](./docs/build/conan.md)
@@ -29,9 +29,12 @@ branch.
 git checkout develop
 ```
 
-
 ## Minimum Requirements
 
+See [System Requirements](https://xrpl.org/system-requirements.html).
+
+Building rippled generally requires git, Python, Conan, CMake, and a C++ compiler. Some guidance on setting up such a [C++ development environment can be found here](./docs/build/environment.md).
+
 - [Python 3.7](https://www.python.org/downloads/)
 - [Conan 1.55](https://conan.io/downloads.html)
 - [CMake 3.16](https://cmake.org/download/)
@@ -46,82 +49,106 @@ The [minimum compiler versions][2] required are:
 | Apple Clang | 13.1.6  |
 | MSVC        | 19.23   |
 
-We don't recommend Windows for `rippled` production at this time. As of
-January 2023, Ubuntu has the highest level of quality assurance, testing,
-and support.
+### Linux
 
-Windows developers should use Visual Studio 2019. `rippled` isn't
-compatible with [Boost](https://www.boost.org/) 1.78 or 1.79, and Conan
-can't build earlier Boost versions.
+The Ubuntu operating system has received the highest level of
+quality assurance, testing, and support.
 
-**Note:** 32-bit Windows development isn't supported.
+Here are [sample instructions for setting up a C++ development environment on Linux](./docs/build/environment.md#linux).
 
+### Mac
 
-## Steps
+Many rippled engineers use macOS for development.
+
+Here are [sample instructions for setting up a C++ development environment on macOS](./docs/build/environment.md#macos).
 
+### Windows
+
+Windows is not recommended for production use at this time.
+
+- Additionally, 32-bit Windows development is not supported.
+- Visual Studio 2022 is not yet supported.
+  - rippled generally requires [Boost][] 1.77, which Conan cannot build with VS 2022.
+  - Until rippled is updated for compatibility with later versions of Boost, Windows developers may need to use Visual Studio 2019.
+
+[Boost]: https://www.boost.org/
+
+## Steps
 
 ### Set Up Conan
 
-1. (Optional) If you've never used Conan, use autodetect to set up a default profile.
+After you have a [C++ development environment](./docs/build/environment.md) ready with Git, Python, Conan, CMake, and a C++ compiler, you may need to set up your Conan profile.
+
+These instructions assume a basic familiarity with Conan and CMake.
+
+If you are unfamiliar with Conan, then please read [this crash course](./docs/build/conan.md) or the official [Getting Started][3] walkthrough.
+
+You'll need at least one Conan profile:
 
    ```
    conan profile new default --detect
    ```
 
-2. Update the compiler settings.
+Update the compiler settings:
 
    ```
    conan profile update settings.compiler.cppstd=20 default
    ```
 
-   Linux developers will commonly have a default Conan [profile][] that compiles
-   with GCC and links with libstdc++.
-   If you are linking with libstdc++ (see profile setting `compiler.libcxx`),
-   then you will need to choose the `libstdc++11` ABI.
+**Linux** developers will commonly have a default Conan [profile][] that compiles
+with GCC and links with libstdc++.
+If you are linking with libstdc++ (see profile setting `compiler.libcxx`),
+then you will need to choose the `libstdc++11` ABI:
 
    ```
    conan profile update settings.compiler.libcxx=libstdc++11 default
    ```
 
-   On Windows, you should use the x64 native build tools.
-   An easy way to do that is to run the shortcut "x64 Native Tools Command
-   Prompt" for the version of Visual Studio that you have installed.
+**Windows** developers may need to use the x64 native build tools.
+An easy way to do that is to run the shortcut "x64 Native Tools Command
+Prompt" for the version of Visual Studio that you have installed.
 
    Windows developers must also build `rippled` and its dependencies for the x64
-   architecture.
+   architecture:
 
    ```
    conan profile update settings.arch=x86_64 default
    ```
 
-3. (Optional) If you have multiple compilers installed on your platform,
-   make sure that Conan and CMake select the one you want to use.
-   This setting will set the correct variables (`CMAKE_<LANG>_COMPILER`)
-   in the generated CMake toolchain file.
+### Multiple compilers
 
-   ```
-   conan profile update 'conf.tools.build:compiler_executables={"c": "<path>", "cpp": "<path>"}' default
-   ```
+When `/usr/bin/g++` exists on a platform, it is the default cpp compiler. This
+default works for some users.
 
-   It should choose the compiler for dependencies as well,
-   but not all of them have a Conan recipe that respects this setting (yet).
-   For the rest, you can set these environment variables:
+However, if this compiler cannot build rippled or its dependencies, then you can
+install another compiler and set Conan and CMake to use it.
+Update the `conf.tools.build:compiler_executables` setting in order to set the correct variables (`CMAKE_<LANG>_COMPILER`) in the
+generated CMake toolchain file.
+For example, on Ubuntu 20, you may have gcc at `/usr/bin/gcc` and g++ at `/usr/bin/g++`; if that is the case, you can select those compilers with:
+```
+conan profile update 'conf.tools.build:compiler_executables={"c": "/usr/bin/gcc", "cpp": "/usr/bin/g++"}' default
+```
 
-   ```
-   conan profile update env.CC=<path> default
-   conan profile update env.CXX=<path> default
-   ```
+Replace `/usr/bin/gcc` and `/usr/bin/g++` with paths to the desired compilers.
+
+It should choose the compiler for dependencies as well,
+but not all of them have a Conan recipe that respects this setting (yet).
+For the rest, you can set these environment variables.
+Replace `<path>` with paths to the desired compilers:
+
+- `conan profile update env.CC=<path> default`
+- `conan profile update env.CXX=<path> default`
 
-4. Export our [Conan recipe for Snappy](./external/snappy).
-   It doesn't explicitly link the C++ standard library,
-   which allows you to statically link it with GCC, if you want.
+Export our [Conan recipe for Snappy](./external/snappy).
+It does not explicitly link the C++ standard library,
+which allows you to statically link it with GCC, if you want.
 
    ```
    conan export external/snappy snappy/1.1.10@
    ```
 
-5. Export our [Conan recipe for SOCI](./external/soci).
-   It patches their CMake to correctly import its dependencies.
+Export our [Conan recipe for SOCI](./external/soci).
+It patches their CMake to correctly import its dependencies.
 
    ```
    conan export external/soci soci/4.0.3@

diff --git a/Builds/CMake/RippledCore.cmake b/Builds/CMake/RippledCore.cmake
@@ -24,6 +24,7 @@ add_library(xrpl::libxrpl ALIAS libxrpl)
 #]===============================]
 target_sources (xrpl_core PRIVATE
   src/ripple/beast/clock/basic_seconds_clock.cpp
+  src/ripple/beast/core/CurrentThreadName.cpp
   src/ripple/beast/core/SemanticVersion.cpp
   src/ripple/beast/hash/impl/xxhash.cpp
   src/ripple/beast/insight/impl/Collector.cpp
@@ -55,7 +56,6 @@ target_sources (xrpl_core PRIVATE
   src/ripple/basics/impl/Log.cpp
   src/ripple/basics/impl/Number.cpp
   src/ripple/basics/impl/StringUtilities.cpp
-  src/ripple/basics/impl/ThreadUtilities.cpp
   #[===============================[
     main sources:
       subdir: json
@@ -103,7 +103,9 @@ target_sources (xrpl_core PRIVATE
   src/ripple/protocol/impl/STObject.cpp
   src/ripple/protocol/impl/STParsedJSON.cpp
   src/ripple/protocol/impl/STPathSet.cpp
+  src/ripple/protocol/impl/STXChainBridge.cpp
   src/ripple/protocol/impl/STTx.cpp
+  src/ripple/protocol/impl/XChainAttestations.cpp
   src/ripple/protocol/impl/STValidation.cpp
   src/ripple/protocol/impl/STVar.cpp
   src/ripple/protocol/impl/STVector256.cpp
@@ -201,7 +203,6 @@ install (
     src/ripple/basics/tagged_integer.h
     src/ripple/basics/SubmitSync.h
     src/ripple/basics/ThreadSafetyAnalysis.h
-    src/ripple/basics/ThreadUtilities.h
     src/ripple/basics/ToString.h
     src/ripple/basics/UnorderedContainers.h
     src/ripple/basics/UptimeClock.h
@@ -243,6 +244,7 @@ install (
     src/ripple/protocol/Indexes.h
     src/ripple/protocol/InnerObjectFormats.h
     src/ripple/protocol/Issue.h
+    src/ripple/protocol/json_get_or_throw.h
     src/ripple/protocol/KeyType.h
     src/ripple/protocol/Keylet.h
     src/ripple/protocol/KnownFormats.h
@@ -273,6 +275,8 @@ install (
     src/ripple/protocol/STParsedJSON.h
     src/ripple/protocol/STPathSet.h
     src/ripple/protocol/STTx.h
+    src/ripple/protocol/XChainAttestations.h
+    src/ripple/protocol/STXChainBridge.h
     src/ripple/protocol/STValidation.h
     src/ripple/protocol/STVector256.h
     src/ripple/protocol/SecretKey.h
@@ -310,6 +314,7 @@ install (
   DESTINATION include/ripple/beast/clock)
 install (
   FILES
+    src/ripple/beast/core/CurrentThreadName.h
     src/ripple/beast/core/LexicalCast.h
     src/ripple/beast/core/List.h
     src/ripple/beast/core/SemanticVersion.h
@@ -528,6 +533,7 @@ target_sources (rippled PRIVATE
   src/ripple/app/tx/impl/SetRegularKey.cpp
   src/ripple/app/tx/impl/SetSignerList.cpp
   src/ripple/app/tx/impl/SetTrust.cpp
+  src/ripple/app/tx/impl/XChainBridge.cpp
   src/ripple/app/tx/impl/SignerEntries.cpp
   src/ripple/app/tx/impl/Taker.cpp
   src/ripple/app/tx/impl/Transactor.cpp
@@ -809,6 +815,7 @@ if (tests)
     src/test/app/ReducedOffer_test.cpp
     src/test/app/Regression_test.cpp
     src/test/app/SHAMapStore_test.cpp
+    src/test/app/XChain_test.cpp
     src/test/app/SetAuth_test.cpp
     src/test/app/SetRegularKey_test.cpp
     src/test/app/SetTrust_test.cpp
@@ -839,7 +846,6 @@ if (tests)
     src/test/basics/Slice_test.cpp
     src/test/basics/StringUtilities_test.cpp
     src/test/basics/TaggedCache_test.cpp
-    src/test/basics/ThreadName_test.cpp
     src/test/basics/XRPAmount_test.cpp
     src/test/basics/base64_test.cpp
     src/test/basics/base_uint_test.cpp
@@ -857,6 +863,7 @@ if (tests)
     src/test/beast/LexicalCast_test.cpp
     src/test/beast/SemanticVersion_test.cpp
     src/test/beast/aged_associative_container_test.cpp
+    src/test/beast/beast_CurrentThreadName_test.cpp
     src/test/beast/beast_Journal_test.cpp
     src/test/beast/beast_PropertyStream_test.cpp
     src/test/beast/beast_Zero_test.cpp
@@ -927,6 +934,7 @@ if (tests)
     src/test/jtx/impl/acctdelete.cpp
     src/test/jtx/impl/account_txn_id.cpp
     src/test/jtx/impl/amount.cpp
+    src/test/jtx/impl/attester.cpp
     src/test/jtx/impl/balance.cpp
     src/test/jtx/impl/check.cpp
     src/test/jtx/impl/delivermin.cpp
@@ -948,6 +956,7 @@ if (tests)
     src/test/jtx/impl/regkey.cpp
     src/test/jtx/impl/sendmax.cpp
     src/test/jtx/impl/seq.cpp
+    src/test/jtx/impl/xchain_bridge.cpp
     src/test/jtx/impl/sig.cpp
     src/test/jtx/impl/tag.cpp
     src/test/jtx/impl/ticket.cpp