XChainBridge: Introduce sidechain support (XLS-38): (#4292)

A bridge connects two blockchains: a locking chain and an issuing
chain (also called a mainchain and a sidechain). Both are independent
ledgers, with their own validators and potentially their own custom
transactions. Importantly, there is a way to move assets from the
locking chain to the issuing chain and a way to return those assets from
the issuing chain back to the locking chain: the bridge. This key
operation is called a cross-chain transfer. A cross-chain transfer is
not a single transaction. It happens on two chains, requires multiple
transactions, and involves an additional server type called a "witness".

A bridge does not exchange assets between two ledgers. Instead, it locks
assets on one ledger (the "locking chain") and represents those assets
with wrapped assets on another chain (the "issuing chain"). A good model
to keep in mind is a box with an infinite supply of wrapped assets.
Putting an asset from the locking chain into the box will release a
wrapped asset onto the issuing chain. Putting a wrapped asset from the
issuing chain back into the box will release one of the existing locking
chain assets back onto the locking chain. There is no other way to get
assets into or out of the box. Note that there is no way for the box to
"run out of" wrapped assets - it has an infinite supply.

Co-authored-by: Gregory Popovitch <greg7mdp@gmail.com>

src/test/rpc/AccountObjects_test.cpp

@@ -23,6 +23,7 @@
 #include <ripple/protocol/jss.h>
 #include <test/jtx.h>
 #include <test/jtx/AMM.h>
+#include <test/jtx/xchain_bridge.h>
 
 #include <boost/utility/string_ref.hpp>
 
@@ -550,7 +551,9 @@ public:
         Account const gw{"gateway"};
         auto const USD = gw["USD"];
 
-        Env env(*this);
+        auto const features =
+            supported_amendments() | FeatureBitset{featureXChainBridge};
+        Env env(*this, features);
 
         // Make a lambda we can use to get "account_objects" easily.
         auto acct_objs = [&env](
@@ -676,6 +679,142 @@ public:
             BEAST_EXPECT(escrow[sfDestination.jsonName] == gw.human());
             BEAST_EXPECT(escrow[sfAmount.jsonName].asUInt() == 100'000'000);
         }
+        {
+            // Create a bridge
+            test::jtx::XChainBridgeObjects x;
+            Env scEnv(*this, envconfig(port_increment, 3), features);
+            x.createScBridgeObjects(scEnv);
+
+            auto scenv_acct_objs = [&](Account const& acct, char const* type) {
+                Json::Value params;
+                params[jss::account] = acct.human();
+                params[jss::type] = type;
+                params[jss::ledger_index] = "validated";
+                return scEnv.rpc("json", "account_objects", to_string(params));
+            };
+
+            Json::Value const resp =
+                scenv_acct_objs(Account::master, jss::bridge);
+
+            BEAST_EXPECT(acct_objs_is_size(resp, 1));
+            auto const& acct_bridge =
+                resp[jss::result][jss::account_objects][0u];
+            BEAST_EXPECT(
+                acct_bridge[sfAccount.jsonName] == Account::master.human());
+            BEAST_EXPECT(
+                acct_bridge[sfLedgerEntryType.getJsonName()] == "Bridge");
+            BEAST_EXPECT(
+                acct_bridge[sfXChainClaimID.getJsonName()].asUInt() == 0);
+            BEAST_EXPECT(
+                acct_bridge[sfXChainAccountClaimCount.getJsonName()].asUInt() ==
+                0);
+            BEAST_EXPECT(
+                acct_bridge[sfXChainAccountCreateCount.getJsonName()]
+                    .asUInt() == 0);
+            BEAST_EXPECT(
+                acct_bridge[sfMinAccountCreateAmount.getJsonName()].asUInt() ==
+                20000000);
+            BEAST_EXPECT(
+                acct_bridge[sfSignatureReward.getJsonName()].asUInt() ==
+                1000000);
+            BEAST_EXPECT(acct_bridge[sfXChainBridge.getJsonName()] == x.jvb);
+        }
+        {
+            // Alice and Bob create a xchain sequence number that we can look
+            // for in the ledger.
+            test::jtx::XChainBridgeObjects x;
+            Env scEnv(*this, envconfig(port_increment, 3), features);
+            x.createScBridgeObjects(scEnv);
+
+            scEnv(
+                xchain_create_claim_id(x.scAlice, x.jvb, x.reward, x.mcAlice));
+            scEnv.close();
+            scEnv(xchain_create_claim_id(x.scBob, x.jvb, x.reward, x.mcBob));
+            scEnv.close();
+
+            auto scenv_acct_objs = [&](Account const& acct, char const* type) {
+                Json::Value params;
+                params[jss::account] = acct.human();
+                params[jss::type] = type;
+                params[jss::ledger_index] = "validated";
+                return scEnv.rpc("json", "account_objects", to_string(params));
+            };
+
+            {
+                // Find the xchain sequence number for Andrea.
+                Json::Value const resp =
+                    scenv_acct_objs(x.scAlice, jss::xchain_owned_claim_id);
+                BEAST_EXPECT(acct_objs_is_size(resp, 1));
+
+                auto const& xchain_seq =
+                    resp[jss::result][jss::account_objects][0u];
+                BEAST_EXPECT(
+                    xchain_seq[sfAccount.jsonName] == x.scAlice.human());
+                BEAST_EXPECT(
+                    xchain_seq[sfXChainClaimID.getJsonName()].asUInt() == 1);
+            }
+            {
+                // and the one for Bob
+                Json::Value const resp =
+                    scenv_acct_objs(x.scBob, jss::xchain_owned_claim_id);
+                BEAST_EXPECT(acct_objs_is_size(resp, 1));
+
+                auto const& xchain_seq =
+                    resp[jss::result][jss::account_objects][0u];
+                BEAST_EXPECT(xchain_seq[sfAccount.jsonName] == x.scBob.human());
+                BEAST_EXPECT(
+                    xchain_seq[sfXChainClaimID.getJsonName()].asUInt() == 2);
+            }
+        }
+        {
+            test::jtx::XChainBridgeObjects x;
+            Env scEnv(*this, envconfig(port_increment, 3), features);
+            x.createScBridgeObjects(scEnv);
+            auto const amt = XRP(1000);
+
+            // send first batch of account create attestations, so the
+            // xchain_create_account_claim_id should be present on the door
+            // account (Account::master) to collect the signatures until a
+            // quorum is reached
+            scEnv(test::jtx::create_account_attestation(
+                x.scAttester,
+                x.jvb,
+                x.mcCarol,
+                amt,
+                x.reward,
+                x.payees[0],
+                true,
+                1,
+                x.scuAlice,
+                x.signers[0]));
+            scEnv.close();
+
+            auto scenv_acct_objs = [&](Account const& acct, char const* type) {
+                Json::Value params;
+                params[jss::account] = acct.human();
+                params[jss::type] = type;
+                params[jss::ledger_index] = "validated";
+                return scEnv.rpc("json", "account_objects", to_string(params));
+            };
+
+            {
+                // Find the xchain_create_account_claim_id
+                Json::Value const resp = scenv_acct_objs(
+                    Account::master, jss::xchain_owned_create_account_claim_id);
+                BEAST_EXPECT(acct_objs_is_size(resp, 1));
+
+                auto const& xchain_create_account_claim_id =
+                    resp[jss::result][jss::account_objects][0u];
+                BEAST_EXPECT(
+                    xchain_create_account_claim_id[sfAccount.jsonName] ==
+                    Account::master.human());
+                BEAST_EXPECT(
+                    xchain_create_account_claim_id[sfXChainAccountCreateCount
+                                                       .getJsonName()]
+                        .asUInt() == 1);
+            }
+        }
+
         // gw creates an offer that we can look for in the ledger.
         env(offer(gw, USD(7), XRP(14)));
         env.close();
@@ -690,7 +829,8 @@ public:
             BEAST_EXPECT(offer[sfTakerPays.jsonName][jss::value].asUInt() == 7);
         }
         {
-            // Create a payment channel from qw to alice that we can look for.
+            // Create a payment channel from qw to alice that we can look
+            // for.
             Json::Value jvPayChan;
             jvPayChan[jss::TransactionType] = jss::PaymentChannelCreate;
             jvPayChan[jss::Flags] = tfUniversal;
@@ -715,7 +855,7 @@ public:
                 payChan[sfSettleDelay.jsonName].asUInt() == 24 * 60 * 60);
         }
         // Make gw multisigning by adding a signerList.
-        env(signers(gw, 6, {{alice, 7}}));
+        env(jtx::signers(gw, 6, {{alice, 7}}));
         env.close();
         {
             // Find the signer list.

src/test/rpc/LedgerRPC_test.cpp

@@ -21,12 +21,331 @@
 #include <ripple/app/misc/TxQ.h>
 #include <ripple/basics/StringUtilities.h>
 #include <ripple/beast/unit_test.h>
+#include <ripple/protocol/AccountID.h>
 #include <ripple/protocol/ErrorCodes.h>
+#include <ripple/protocol/STXChainBridge.h>
 #include <ripple/protocol/jss.h>
 #include <test/jtx.h>
+#include <test/jtx/attester.h>
+#include <test/jtx/multisign.h>
+#include <test/jtx/xchain_bridge.h>
 
 namespace ripple {
 
+class LedgerRPC_XChain_test : public beast::unit_test::suite,
+                              public test::jtx::XChainBridgeObjects
+{
+    void
+    checkErrorValue(
+        Json::Value const& jv,
+        std::string const& err,
+        std::string const& msg)
+    {
+        if (BEAST_EXPECT(jv.isMember(jss::status)))
+            BEAST_EXPECT(jv[jss::status] == "error");
+        if (BEAST_EXPECT(jv.isMember(jss::error)))
+            BEAST_EXPECT(jv[jss::error] == err);
+        if (msg.empty())
+        {
+            BEAST_EXPECT(
+                jv[jss::error_message] == Json::nullValue ||
+                jv[jss::error_message] == "");
+        }
+        else if (BEAST_EXPECT(jv.isMember(jss::error_message)))
+            BEAST_EXPECT(jv[jss::error_message] == msg);
+    }
+
+    void
+    testLedgerEntryBridge()
+    {
+        testcase("ledger_entry: bridge");
+        using namespace test::jtx;
+
+        Env mcEnv{*this, features};
+        Env scEnv(*this, envconfig(port_increment, 3), features);
+
+        createBridgeObjects(mcEnv, scEnv);
+
+        std::string const ledgerHash{to_string(mcEnv.closed()->info().hash)};
+        std::string bridge_index;
+        Json::Value mcBridge;
+        {
+            // request the bridge via RPC
+            Json::Value jvParams;
+            jvParams[jss::bridge_account] = mcDoor.human();
+            jvParams[jss::bridge] = jvb;
+            Json::Value const jrr = mcEnv.rpc(
+                "json", "ledger_entry", to_string(jvParams))[jss::result];
+
+            BEAST_EXPECT(jrr.isMember(jss::node));
+            auto r = jrr[jss::node];
+            // std::cout << to_string(r) << '\n';
+
+            BEAST_EXPECT(r.isMember(jss::Account));
+            BEAST_EXPECT(r[jss::Account] == mcDoor.human());
+
+            BEAST_EXPECT(r.isMember(jss::Flags));
+
+            BEAST_EXPECT(r.isMember(sfLedgerEntryType.jsonName));
+            BEAST_EXPECT(r[sfLedgerEntryType.jsonName] == jss::Bridge);
+
+            // we not created an account yet
+            BEAST_EXPECT(r.isMember(sfXChainAccountCreateCount.jsonName));
+            BEAST_EXPECT(r[sfXChainAccountCreateCount.jsonName].asInt() == 0);
+
+            // we have not claimed a locking chain tx yet
+            BEAST_EXPECT(r.isMember(sfXChainAccountClaimCount.jsonName));
+            BEAST_EXPECT(r[sfXChainAccountClaimCount.jsonName].asInt() == 0);
+
+            BEAST_EXPECT(r.isMember(jss::index));
+            bridge_index = r[jss::index].asString();
+            mcBridge = r;
+        }
+        {
+            // request the bridge via RPC by index
+            Json::Value jvParams;
+            jvParams[jss::index] = bridge_index;
+            Json::Value const jrr = mcEnv.rpc(
+                "json", "ledger_entry", to_string(jvParams))[jss::result];
+
+            BEAST_EXPECT(jrr.isMember(jss::node));
+            BEAST_EXPECT(jrr[jss::node] == mcBridge);
+        }
+        {
+            // swap door accounts and make sure we get an error value
+            Json::Value jvParams;
+            // Sidechain door account is "master", not scDoor
+            jvParams[jss::bridge_account] = Account::master.human();
+            jvParams[jss::bridge] = jvb;
+            jvParams[jss::ledger_hash] = ledgerHash;
+            Json::Value const jrr = mcEnv.rpc(
+                "json", "ledger_entry", to_string(jvParams))[jss::result];
+
+            checkErrorValue(jrr, "entryNotFound", "");
+        }
+        {
+            // create two claim ids and verify that the bridge counter was
+            // incremented
+            mcEnv(xchain_create_claim_id(mcAlice, jvb, reward, scAlice));
+            mcEnv.close();
+            mcEnv(xchain_create_claim_id(mcBob, jvb, reward, scBob));
+            mcEnv.close();
+
+            // request the bridge via RPC
+            Json::Value jvParams;
+            jvParams[jss::bridge_account] = mcDoor.human();
+            jvParams[jss::bridge] = jvb;
+            // std::cout << to_string(jvParams) << '\n';
+            Json::Value const jrr = mcEnv.rpc(
+                "json", "ledger_entry", to_string(jvParams))[jss::result];
+
+            BEAST_EXPECT(jrr.isMember(jss::node));
+            auto r = jrr[jss::node];
+
+            // we executed two create claim id txs
+            BEAST_EXPECT(r.isMember(sfXChainClaimID.jsonName));
+            BEAST_EXPECT(r[sfXChainClaimID.jsonName].asInt() == 2);
+        }
+    }
+
+    void
+    testLedgerEntryClaimID()
+    {
+        testcase("ledger_entry: xchain_claim_id");
+        using namespace test::jtx;
+
+        Env mcEnv{*this, features};
+        Env scEnv(*this, envconfig(port_increment, 3), features);
+
+        createBridgeObjects(mcEnv, scEnv);
+
+        scEnv(xchain_create_claim_id(scAlice, jvb, reward, mcAlice));
+        scEnv.close();
+        scEnv(xchain_create_claim_id(scBob, jvb, reward, mcBob));
+        scEnv.close();
+
+        std::string bridge_index;
+        {
+            // request the xchain_claim_id via RPC
+            Json::Value jvParams;
+            jvParams[jss::xchain_owned_claim_id] = jvXRPBridgeRPC;
+            jvParams[jss::xchain_owned_claim_id][jss::xchain_owned_claim_id] =
+                1;
+            // std::cout << to_string(jvParams) << '\n';
+            Json::Value const jrr = scEnv.rpc(
+                "json", "ledger_entry", to_string(jvParams))[jss::result];
+
+            BEAST_EXPECT(jrr.isMember(jss::node));
+            auto r = jrr[jss::node];
+            // std::cout << to_string(r) << '\n';
+
+            BEAST_EXPECT(r.isMember(jss::Account));
+            BEAST_EXPECT(r[jss::Account] == scAlice.human());
+            BEAST_EXPECT(
+                r[sfLedgerEntryType.jsonName] == jss::XChainOwnedClaimID);
+            BEAST_EXPECT(r[sfXChainClaimID.jsonName].asInt() == 1);
+            BEAST_EXPECT(r[sfOwnerNode.jsonName].asInt() == 0);
+        }
+
+        {
+            // request the xchain_claim_id via RPC
+            Json::Value jvParams;
+            jvParams[jss::xchain_owned_claim_id] = jvXRPBridgeRPC;
+            jvParams[jss::xchain_owned_claim_id][jss::xchain_owned_claim_id] =
+                2;
+            Json::Value const jrr = scEnv.rpc(
+                "json", "ledger_entry", to_string(jvParams))[jss::result];
+
+            BEAST_EXPECT(jrr.isMember(jss::node));
+            auto r = jrr[jss::node];
+            // std::cout << to_string(r) << '\n';
+
+            BEAST_EXPECT(r.isMember(jss::Account));
+            BEAST_EXPECT(r[jss::Account] == scBob.human());
+            BEAST_EXPECT(
+                r[sfLedgerEntryType.jsonName] == jss::XChainOwnedClaimID);
+            BEAST_EXPECT(r[sfXChainClaimID.jsonName].asInt() == 2);
+            BEAST_EXPECT(r[sfOwnerNode.jsonName].asInt() == 0);
+        }
+    }
+
+    void
+    testLedgerEntryCreateAccountClaimID()
+    {
+        testcase("ledger_entry: xchain_create_account_claim_id");
+        using namespace test::jtx;
+
+        Env mcEnv{*this, features};
+        Env scEnv(*this, envconfig(port_increment, 3), features);
+
+        // note: signers.size() and quorum are both 5 in createBridgeObjects
+        createBridgeObjects(mcEnv, scEnv);
+
+        auto scCarol =
+            Account("scCarol");  // Don't fund it - it will be created with the
+                                 // xchain transaction
+        auto const amt = XRP(1000);
+        mcEnv(sidechain_xchain_account_create(
+            mcAlice, jvb, scCarol, amt, reward));
+        mcEnv.close();
+
+        // send less than quorum of attestations (otherwise funds are
+        // immediately transferred and no "claim" object is created)
+        size_t constexpr num_attest = 3;
+        auto attestations = create_account_attestations(
+            scAttester,
+            jvb,
+            mcAlice,
+            amt,
+            reward,
+            payee,
+            /*wasLockingChainSend*/ true,
+            1,
+            scCarol,
+            signers,
+            UT_XCHAIN_DEFAULT_NUM_SIGNERS);
+        for (size_t i = 0; i < num_attest; ++i)
+        {
+            scEnv(attestations[i]);
+        }
+        scEnv.close();
+
+        {
+            // request the create account claim_id via RPC
+            Json::Value jvParams;
+            jvParams[jss::xchain_owned_create_account_claim_id] =
+                jvXRPBridgeRPC;
+            jvParams[jss::xchain_owned_create_account_claim_id]
+                    [jss::xchain_owned_create_account_claim_id] = 1;
+            // std::cout << to_string(jvParams) << '\n';
+            Json::Value const jrr = scEnv.rpc(
+                "json", "ledger_entry", to_string(jvParams))[jss::result];
+            // std::cout << to_string(jrr) << '\n';
+
+            BEAST_EXPECT(jrr.isMember(jss::node));
+            auto r = jrr[jss::node];
+
+            BEAST_EXPECT(r.isMember(jss::Account));
+            BEAST_EXPECT(r[jss::Account] == Account::master.human());
+
+            BEAST_EXPECT(r.isMember(sfXChainAccountCreateCount.jsonName));
+            BEAST_EXPECT(r[sfXChainAccountCreateCount.jsonName].asInt() == 1);
+
+            BEAST_EXPECT(
+                r.isMember(sfXChainCreateAccountAttestations.jsonName));
+            auto attest = r[sfXChainCreateAccountAttestations.jsonName];
+            BEAST_EXPECT(attest.isArray());
+            BEAST_EXPECT(attest.size() == 3);
+            BEAST_EXPECT(attest[Json::Value::UInt(0)].isMember(
+                sfXChainCreateAccountProofSig.jsonName));
+            Json::Value a[num_attest];
+            for (size_t i = 0; i < num_attest; ++i)
+            {
+                a[i] = attest[Json::Value::UInt(0)]
+                             [sfXChainCreateAccountProofSig.jsonName];
+                BEAST_EXPECT(
+                    a[i].isMember(jss::Amount) &&
+                    a[i][jss::Amount].asInt() == 1000 * drop_per_xrp);
+                BEAST_EXPECT(
+                    a[i].isMember(jss::Destination) &&
+                    a[i][jss::Destination] == scCarol.human());
+                BEAST_EXPECT(
+                    a[i].isMember(sfAttestationSignerAccount.jsonName) &&
+                    std::any_of(
+                        signers.begin(), signers.end(), [&](signer const& s) {
+                            return a[i][sfAttestationSignerAccount.jsonName] ==
+                                s.account.human();
+                        }));
+                BEAST_EXPECT(
+                    a[i].isMember(sfAttestationRewardAccount.jsonName) &&
+                    std::any_of(
+                        payee.begin(),
+                        payee.end(),
+                        [&](Account const& account) {
+                            return a[i][sfAttestationRewardAccount.jsonName] ==
+                                account.human();
+                        }));
+                BEAST_EXPECT(
+                    a[i].isMember(sfWasLockingChainSend.jsonName) &&
+                    a[i][sfWasLockingChainSend.jsonName] == 1);
+                BEAST_EXPECT(
+                    a[i].isMember(sfSignatureReward.jsonName) &&
+                    a[i][sfSignatureReward.jsonName].asInt() ==
+                        1 * drop_per_xrp);
+            }
+        }
+
+        // complete attestations quorum - CreateAccountClaimID should not be
+        // present anymore
+        for (size_t i = num_attest; i < UT_XCHAIN_DEFAULT_NUM_SIGNERS; ++i)
+        {
+            scEnv(attestations[i]);
+        }
+        scEnv.close();
+        {
+            // request the create account claim_id via RPC
+            Json::Value jvParams;
+            jvParams[jss::xchain_owned_create_account_claim_id] =
+                jvXRPBridgeRPC;
+            jvParams[jss::xchain_owned_create_account_claim_id]
+                    [jss::xchain_owned_create_account_claim_id] = 1;
+            // std::cout << to_string(jvParams) << '\n';
+            Json::Value const jrr = scEnv.rpc(
+                "json", "ledger_entry", to_string(jvParams))[jss::result];
+            checkErrorValue(jrr, "entryNotFound", "");
+        }
+    }
+
+public:
+    void
+    run() override
+    {
+        testLedgerEntryBridge();
+        testLedgerEntryClaimID();
+        testLedgerEntryCreateAccountClaimID();
+    }
+};
+
 class LedgerRPC_test : public beast::unit_test::suite
 {
     void
@@ -1940,5 +2259,6 @@ public:
 };
 
 BEAST_DEFINE_TESTSUITE(LedgerRPC, app, ripple);
+BEAST_DEFINE_TESTSUITE(LedgerRPC_XChain, app, ripple);
 
 }  // namespace ripple

src/test/rpc/Subscribe_test.cpp

@@ -25,6 +25,7 @@
 #include <test/jtx.h>
 #include <test/jtx/WSClient.h>
 #include <test/jtx/envconfig.h>
+#include <tuple>
 
 namespace ripple {
 namespace test {
@@ -743,7 +744,7 @@ public:
 
         using namespace std::chrono_literals;
         using namespace jtx;
-        using IdxHashVec = std::vector<std::pair<int, std::string>>;
+        using IdxHashVec = std::vector<std::tuple<int, std::string, bool, int>>;
 
         Account alice("alice");
         Account bob("bob");
@@ -781,11 +782,14 @@ public:
                         idx = r[jss::account_history_tx_index].asInt();
                     if (r.isMember(jss::account_history_tx_first))
                         first_flag = true;
+                    bool boundary = r.isMember(jss::account_history_boundary);
+                    int ledger_idx = r[jss::ledger_index].asInt();
                     if (r.isMember(jss::transaction) &&
                         r[jss::transaction].isMember(jss::hash))
                     {
+                        auto t{r[jss::transaction]};
                         v.emplace_back(
-                            idx, r[jss::transaction][jss::hash].asString());
+                            idx, t[jss::hash].asString(), boundary, ledger_idx);
                         continue;
                     }
                 }
@@ -838,13 +842,13 @@ public:
             hash_map<std::string, int> txHistoryMap;
             for (auto const& tx : txHistoryVec)
             {
-                txHistoryMap.emplace(tx.second, tx.first);
+                txHistoryMap.emplace(std::get<1>(tx), std::get<0>(tx));
             }
 
             auto getHistoryIndex = [&](std::size_t i) -> std::optional<int> {
                 if (i >= accountVec.size())
                     return {};
-                auto it = txHistoryMap.find(accountVec[i].second);
+                auto it = txHistoryMap.find(std::get<1>(accountVec[i]));
                 if (it == txHistoryMap.end())
                     return {};
                 return it->second;
@@ -862,6 +866,48 @@ public:
             return true;
         };
 
+        // example of vector created from the return of `subscribe` rpc
+        // with jss::accounts
+        // boundary == true on last tx of ledger
+        // ------------------------------------------------------------
+        // (0, "E5B8B...", false, 4
+        // (0, "39E1C...", false, 4
+        // (0, "14EF1...", false, 4
+        // (0, "386E6...", false, 4
+        // (0, "00F3B...", true,  4
+        // (0, "1DCDC...", false, 5
+        // (0, "BD02A...", false, 5
+        // (0, "D3E16...", false, 5
+        // (0, "CB593...", false, 5
+        // (0, "8F28B...", true,  5
+        //
+        // example of vector created from the return of `subscribe` rpc
+        // with jss::account_history_tx_stream.
+        // boundary == true on first tx of ledger
+        // ------------------------------------------------------------
+        // (-1, "8F28B...", false, 5
+        // (-2, "CB593...", false, 5
+        // (-3, "D3E16...", false, 5
+        // (-4, "BD02A...", false, 5
+        // (-5, "1DCDC...", true,  5
+        // (-6, "00F3B...", false, 4
+        // (-7, "386E6...", false, 4
+        // (-8, "14EF1...", false, 4
+        // (-9, "39E1C...", false, 4
+        // (-10, "E5B8B...", true, 4
+
+        auto checkBoundary = [](IdxHashVec const& vec, bool /* forward */) {
+            size_t num_tx = vec.size();
+            for (size_t i = 0; i < num_tx; ++i)
+            {
+                auto [idx, hash, boundary, ledger] = vec[i];
+                if ((i + 1 == num_tx || ledger != std::get<3>(vec[i + 1])) !=
+                    boundary)
+                    return false;
+            }
+            return true;
+        };
+
         ///////////////////////////////////////////////////////////////////
 
         {
@@ -880,6 +926,7 @@ public:
             auto jv = wscTxHistory->invoke("subscribe", request);
             if (!BEAST_EXPECT(goodSubRPC(jv)))
                 return;
+
             jv = wscTxHistory->invoke("subscribe", request);
             BEAST_EXPECT(!goodSubRPC(jv));
 
@@ -911,7 +958,6 @@ public:
             r = getTxHash(*wscTxHistory, vec, 1);
             BEAST_EXPECT(!r.first);
         }
-
         {
             /*
              * subscribe genesis account tx history without txns
@@ -950,8 +996,8 @@ public:
             if (!BEAST_EXPECT(r.first && r.second))
                 return;
             BEAST_EXPECT(
-                bobFullHistoryVec.back().second ==
-                genesisFullHistoryVec.back().second);
+                std::get<1>(bobFullHistoryVec.back()) ==
+                std::get<1>(genesisFullHistoryVec.back()));
 
             /*
              * unsubscribe to prepare next test
@@ -987,8 +1033,8 @@ public:
             jv = wscTxHistory->invoke("unsubscribe", request);
 
             BEAST_EXPECT(
-                bobFullHistoryVec.back().second ==
-                genesisFullHistoryVec.back().second);
+                std::get<1>(bobFullHistoryVec.back()) ==
+                std::get<1>(genesisFullHistoryVec.back()));
         }
 
         {
@@ -1030,11 +1076,17 @@ public:
             if (!BEAST_EXPECT(hashCompare(accountVec, txHistoryVec, true)))
                 return;
 
+            // check boundary tags
+            // only account_history_tx_stream has ledger boundary information.
+            if (!BEAST_EXPECT(checkBoundary(txHistoryVec, false)))
+                return;
+
             {
                 // take out all history txns from stream to prepare next test
                 IdxHashVec initFundTxns;
                 if (!BEAST_EXPECT(
-                        getTxHash(*wscTxHistory, initFundTxns, 10).second))
+                        getTxHash(*wscTxHistory, initFundTxns, 10).second) ||
+                    !BEAST_EXPECT(checkBoundary(initFundTxns, false)))
                     return;
             }
 
@@ -1046,6 +1098,12 @@ public:
                 return;
             if (!BEAST_EXPECT(hashCompare(accountVec, txHistoryVec, true)))
                 return;
+
+            // check boundary tags
+            // only account_history_tx_stream has ledger boundary information.
+            if (!BEAST_EXPECT(checkBoundary(txHistoryVec, false)))
+                return;
+
             wscTxHistory->invoke("unsubscribe", request);
             wscAccount->invoke("unsubscribe", stream);
         }