Tx stream resource balance change and transaction status filter

CHANGELOG.md

@@ -1,3 +1,15 @@
+## 1.10.0
+Release built: _not released yet_
+
+### API Changes
+- Two new filters to `/stream/transactions` endpoint.
+  - `transaction_status_filter` - Allows filtering by transaction status (`Successful`,`Failed`, `All`). Defaults to `All`.
+  - `balance_change_resources_filter` - Allows specifying an array of resources. If specified, the response will contain transactions which included non-fee related balance changes for all resources.
+
+### Database changes
+- New entries added to the `ledger_transaction_markers` table for each resource whose balance (excluding fee-related changes) was modified in a transaction. Each resource balance change will be represented by an entry with the `resource_balance_change` discriminator and the resource's `entity_id`.
+- Removed `transaction_type.round_update` from the `ledger_transaction_markers` table. This should reduce database size and slightly improve the performance of the `/stream/transactions` endpoint.
+
 ## 1.9.2
 Release built: 9.12.2024
 

src/RadixDlt.NetworkGateway.Abstractions/Model/LedgerTransactionMarkerType.cs

@@ -73,4 +73,5 @@ public enum LedgerTransactionMarkerType
     ManifestClass,
     EventGlobalEmitter,
     EpochChange,
+    ResourceBalanceChange,
 }

src/RadixDlt.NetworkGateway.Abstractions/Model/LedgerTransactionStatusFilter.cs

@@ -0,0 +1,72 @@
+/* Copyright 2021 Radix Publishing Ltd incorporated in Jersey (Channel Islands).
+ *
+ * Licensed under the Radix License, Version 1.0 (the "License"); you may not use this
+ * file except in compliance with the License. You may obtain a copy of the License at:
+ *
+ * radixfoundation.org/licenses/LICENSE-v1
+ *
+ * The Licensor hereby grants permission for the Canonical version of the Work to be
+ * published, distributed and used under or by reference to the Licensor’s trademark
+ * Radix ® and use of any unregistered trade names, logos or get-up.
+ *
+ * The Licensor provides the Work (and each Contributor provides its Contributions) on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied,
+ * including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT,
+ * MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE.
+ *
+ * Whilst the Work is capable of being deployed, used and adopted (instantiated) to create
+ * a distributed ledger it is your responsibility to test and validate the code, together
+ * with all logic and performance of that code under all foreseeable scenarios.
+ *
+ * The Licensor does not make or purport to make and hereby excludes liability for all
+ * and any representation, warranty or undertaking in any form whatsoever, whether express
+ * or implied, to any entity or person, including any representation, warranty or
+ * undertaking, as to the functionality security use, value or other characteristics of
+ * any distributed ledger nor in respect the functioning or value of any tokens which may
+ * be created stored or transferred using the Work. The Licensor does not warrant that the
+ * Work or any use of the Work complies with any law or regulation in any territory where
+ * it may be implemented or used or that it will be appropriate for any specific purpose.
+ *
+ * Neither the licensor nor any current or former employees, officers, directors, partners,
+ * trustees, representatives, agents, advisors, contractors, or volunteers of the Licensor
+ * shall be liable for any direct or indirect, special, incidental, consequential or other
+ * losses of any kind, in tort, contract or otherwise (including but not limited to loss
+ * of revenue, income or profits, or loss of use or data, or loss of reputation, or loss
+ * of any economic or other opportunity of whatsoever nature or howsoever arising), arising
+ * out of or in connection with (without limitation of any use, misuse, of any ledger system
+ * or use made or its functionality or any performance or operation of any code or protocol
+ * caused by bugs or programming or logic errors or otherwise);
+ *
+ * A. any offer, purchase, holding, use, sale, exchange or transmission of any
+ * cryptographic keys, tokens or assets created, exchanged, stored or arising from any
+ * interaction with the Work;
+ *
+ * B. any failure in a transmission or loss of any token or assets keys or other digital
+ * artefacts due to errors in transmission;
+ *
+ * C. bugs, hacks, logic errors or faults in the Work or any communication;
+ *
+ * D. system software or apparatus including but not limited to losses caused by errors
+ * in holding or transmitting tokens by any third-party;
+ *
+ * E. breaches or failure of security including hacker attacks, loss or disclosure of
+ * password, loss of private key, unauthorised use or misuse of such passwords or keys;
+ *
+ * F. any losses including loss of anticipated savings or other benefits resulting from
+ * use of the Work or any changes to the Work (however implemented).
+ *
+ * You are solely responsible for; testing, validating and evaluation of all operation
+ * logic, functionality, security and appropriateness of using the Work for any commercial
+ * or non-commercial purpose and for any reproduction or redistribution by You of the
+ * Work. You assume all risks associated with Your use of the Work and the exercise of
+ * permissions under this License.
+ */
+
+namespace RadixDlt.NetworkGateway.Abstractions.Model;
+
+public enum LedgerTransactionStatusFilter
+{
+    Successful,
+    Failed,
+    All,
+}

src/RadixDlt.NetworkGateway.GatewayApi/Handlers/DefaultTransactionHandler.cs

@@ -172,9 +172,17 @@ public DefaultTransactionHandler(
             _ => throw new UnreachableException($"Didn't expect {request.KindFilter} value"),
         };
 
+        var statusFilter = request.TransactionStatusFilter switch
+        {
+            GatewayModel.StreamTransactionsRequest.TransactionStatusFilterEnum.Successful => LedgerTransactionStatusFilter.Successful,
+            GatewayModel.StreamTransactionsRequest.TransactionStatusFilterEnum.Failed => LedgerTransactionStatusFilter.Failed,
+            _ => LedgerTransactionStatusFilter.All,
+        };
+
         var searchCriteria = new TransactionStreamPageRequestSearchCriteria
         {
             Kind = kindFilter,
+            Status = statusFilter,
         };
 
         request.AffectedGlobalEntitiesFilter?.ForEach(a => searchCriteria.AffectedGlobalEntities.Add((EntityAddress)a));
@@ -183,6 +191,7 @@ public DefaultTransactionHandler(
         request.ManifestAccountsWithdrawnFromFilter?.ForEach(a => searchCriteria.ManifestAccountsWithdrawnFrom.Add((EntityAddress)a));
         request.ManifestBadgesPresentedFilter?.ForEach(a => searchCriteria.BadgesPresented.Add((EntityAddress)a));
         request.ManifestResourcesFilter?.ForEach(a => searchCriteria.ManifestResources.Add((EntityAddress)a));
+        request.BalanceChangeResourcesFilter?.ForEach(a => searchCriteria.BalanceChangeResources.Add((EntityAddress)a));
         request.EventsFilter?.ForEach(ef =>
         {
             var eventType = ef.Event switch

src/RadixDlt.NetworkGateway.GatewayApi/Services/ITransactionQuerier.cs

@@ -110,6 +110,8 @@ public sealed record TransactionStreamPageRequest(
 
 public class TransactionStreamPageRequestSearchCriteria
 {
+    public LedgerTransactionStatusFilter Status { get; set; }
+
     public LedgerTransactionKindFilter Kind { get; set; }
 
     public HashSet<LedgerTransactionEventFilter> Events { get; set; } = new();
@@ -130,5 +132,7 @@ public class TransactionStreamPageRequestSearchCriteria
 
     public HashSet<EntityAddress> AccountsWithManifestOwnerMethodCalls { get; set; } = new();
 
+    public HashSet<EntityAddress> BalanceChangeResources { get; set; } = new();
+
     public ManifestClassFilter? ManifestClassFilter { get; set; }
 }

src/RadixDlt.NetworkGateway.GatewayApi/gateway-api-schema.yaml

@@ -4357,6 +4357,19 @@ components:
               type: array
               items:
                 $ref: "#/components/schemas/Address"
+            balance_change_resources_filter:
+              description: Allows specifying an array of resources. If specified, the response will contain transactions which included non-fee related balance changes for all resources.
+              type: array
+              items:
+                $ref: "#/components/schemas/Address"
+            transaction_status_filter:
+              description: Allows filtering by transaction status. Defaults to `All`.
+              type: string
+              default: All
+              enum:
+                - Successful
+                - Failed
+                - All
             order:
               description: Configures the order of returned result set. Defaults to `desc`.
               type: string

src/RadixDlt.NetworkGateway.GatewayApiSdk/generated/Model/StreamTransactionsRequest.cs

@@ -130,6 +130,40 @@ public enum KindFilterEnum
         [DataMember(Name = "kind_filter", EmitDefaultValue = true)]
         public KindFilterEnum? KindFilter { get; set; }
         /// <summary>
+        /// Allows filtering by transaction status. Defaults to &#x60;All&#x60;.
+        /// </summary>
+        /// <value>Allows filtering by transaction status. Defaults to &#x60;All&#x60;.</value>
+        [JsonConverter(typeof(StringEnumConverter))]
+        public enum TransactionStatusFilterEnum
+        {
+            /// <summary>
+            /// Enum Successful for value: Successful
+            /// </summary>
+            [EnumMember(Value = "Successful")]
+            Successful = 1,
+
+            /// <summary>
+            /// Enum Failed for value: Failed
+            /// </summary>
+            [EnumMember(Value = "Failed")]
+            Failed = 2,
+
+            /// <summary>
+            /// Enum All for value: All
+            /// </summary>
+            [EnumMember(Value = "All")]
+            All = 3
+
+        }
+
+
+        /// <summary>
+        /// Allows filtering by transaction status. Defaults to &#x60;All&#x60;.
+        /// </summary>
+        /// <value>Allows filtering by transaction status. Defaults to &#x60;All&#x60;.</value>
+        [DataMember(Name = "transaction_status_filter", EmitDefaultValue = true)]
+        public TransactionStatusFilterEnum? TransactionStatusFilter { get; set; }
+        /// <summary>
         /// Configures the order of returned result set. Defaults to &#x60;desc&#x60;.
         /// </summary>
         /// <value>Configures the order of returned result set. Defaults to &#x60;desc&#x60;.</value>
@@ -175,9 +209,11 @@ public enum OrderEnum
         /// <param name="accountsWithoutManifestOwnerMethodCalls">Allows specifying an array of account addresses. If specified, the response will contain only transactions that, for all specified accounts, do NOT contain manifest method calls to that account which require owner role. See the [account docs](https://docs.radixdlt.com/docs/account) for more information..</param>
         /// <param name="manifestClassFilter">manifestClassFilter.</param>
         /// <param name="eventGlobalEmittersFilter">Allows specifying an array of global addresses. If specified, the response will contain transactions in which all entities emitted events. If an event was published by an internal entity, it is going to be indexed as it is a global ancestor. For performance reasons events published by consensus manager and native XRD resource are excluded from that filter..</param>
+        /// <param name="balanceChangeResourcesFilter">Allows specifying an array of resources. If specified, the response will contain transactions which included non-fee related balance changes for all resources..</param>
+        /// <param name="transactionStatusFilter">Allows filtering by transaction status. Defaults to &#x60;All&#x60;. (default to TransactionStatusFilterEnum.All).</param>
         /// <param name="order">Configures the order of returned result set. Defaults to &#x60;desc&#x60;..</param>
         /// <param name="optIns">optIns.</param>
-        public StreamTransactionsRequest(LedgerStateSelector atLedgerState = default(LedgerStateSelector), LedgerStateSelector fromLedgerState = default(LedgerStateSelector), string cursor = default(string), int? limitPerPage = default(int?), KindFilterEnum? kindFilter = default(KindFilterEnum?), List<string> manifestAccountsWithdrawnFromFilter = default(List<string>), List<string> manifestAccountsDepositedIntoFilter = default(List<string>), List<string> manifestBadgesPresentedFilter = default(List<string>), List<string> manifestResourcesFilter = default(List<string>), List<string> affectedGlobalEntitiesFilter = default(List<string>), List<StreamTransactionsRequestEventFilterItem> eventsFilter = default(List<StreamTransactionsRequestEventFilterItem>), List<string> accountsWithManifestOwnerMethodCalls = default(List<string>), List<string> accountsWithoutManifestOwnerMethodCalls = default(List<string>), StreamTransactionsRequestAllOfManifestClassFilter manifestClassFilter = default(StreamTransactionsRequestAllOfManifestClassFilter), List<string> eventGlobalEmittersFilter = default(List<string>), OrderEnum? order = default(OrderEnum?), TransactionDetailsOptIns optIns = default(TransactionDetailsOptIns))
+        public StreamTransactionsRequest(LedgerStateSelector atLedgerState = default(LedgerStateSelector), LedgerStateSelector fromLedgerState = default(LedgerStateSelector), string cursor = default(string), int? limitPerPage = default(int?), KindFilterEnum? kindFilter = default(KindFilterEnum?), List<string> manifestAccountsWithdrawnFromFilter = default(List<string>), List<string> manifestAccountsDepositedIntoFilter = default(List<string>), List<string> manifestBadgesPresentedFilter = default(List<string>), List<string> manifestResourcesFilter = default(List<string>), List<string> affectedGlobalEntitiesFilter = default(List<string>), List<StreamTransactionsRequestEventFilterItem> eventsFilter = default(List<StreamTransactionsRequestEventFilterItem>), List<string> accountsWithManifestOwnerMethodCalls = default(List<string>), List<string> accountsWithoutManifestOwnerMethodCalls = default(List<string>), StreamTransactionsRequestAllOfManifestClassFilter manifestClassFilter = default(StreamTransactionsRequestAllOfManifestClassFilter), List<string> eventGlobalEmittersFilter = default(List<string>), List<string> balanceChangeResourcesFilter = default(List<string>), TransactionStatusFilterEnum? transactionStatusFilter = TransactionStatusFilterEnum.All, OrderEnum? order = default(OrderEnum?), TransactionDetailsOptIns optIns = default(TransactionDetailsOptIns))
         {
             this.AtLedgerState = atLedgerState;
             this.FromLedgerState = fromLedgerState;
@@ -194,6 +230,8 @@ public enum OrderEnum
             this.AccountsWithoutManifestOwnerMethodCalls = accountsWithoutManifestOwnerMethodCalls;
             this.ManifestClassFilter = manifestClassFilter;
             this.EventGlobalEmittersFilter = eventGlobalEmittersFilter;
+            this.BalanceChangeResourcesFilter = balanceChangeResourcesFilter;
+            this.TransactionStatusFilter = transactionStatusFilter;
             this.Order = order;
             this.OptIns = optIns;
         }
@@ -293,6 +331,13 @@ public enum OrderEnum
         [DataMember(Name = "event_global_emitters_filter", EmitDefaultValue = true)]
         public List<string> EventGlobalEmittersFilter { get; set; }
 
+        /// <summary>
+        /// Allows specifying an array of resources. If specified, the response will contain transactions which included non-fee related balance changes for all resources.
+        /// </summary>
+        /// <value>Allows specifying an array of resources. If specified, the response will contain transactions which included non-fee related balance changes for all resources.</value>
+        [DataMember(Name = "balance_change_resources_filter", EmitDefaultValue = true)]
+        public List<string> BalanceChangeResourcesFilter { get; set; }
+
         /// <summary>
         /// Gets or Sets OptIns
         /// </summary>
@@ -322,6 +367,8 @@ public override string ToString()
             sb.Append("  AccountsWithoutManifestOwnerMethodCalls: ").Append(AccountsWithoutManifestOwnerMethodCalls).Append("\n");
             sb.Append("  ManifestClassFilter: ").Append(ManifestClassFilter).Append("\n");
             sb.Append("  EventGlobalEmittersFilter: ").Append(EventGlobalEmittersFilter).Append("\n");
+            sb.Append("  BalanceChangeResourcesFilter: ").Append(BalanceChangeResourcesFilter).Append("\n");
+            sb.Append("  TransactionStatusFilter: ").Append(TransactionStatusFilter).Append("\n");
             sb.Append("  Order: ").Append(Order).Append("\n");
             sb.Append("  OptIns: ").Append(OptIns).Append("\n");
             sb.Append("}\n");
@@ -442,6 +489,16 @@ public bool Equals(StreamTransactionsRequest input)
                     input.EventGlobalEmittersFilter != null &&
                     this.EventGlobalEmittersFilter.SequenceEqual(input.EventGlobalEmittersFilter)
                 ) && 
+                (
+                    this.BalanceChangeResourcesFilter == input.BalanceChangeResourcesFilter ||
+                    this.BalanceChangeResourcesFilter != null &&
+                    input.BalanceChangeResourcesFilter != null &&
+                    this.BalanceChangeResourcesFilter.SequenceEqual(input.BalanceChangeResourcesFilter)
+                ) && 
+                (
+                    this.TransactionStatusFilter == input.TransactionStatusFilter ||
+                    this.TransactionStatusFilter.Equals(input.TransactionStatusFilter)
+                ) && 
                 (
                     this.Order == input.Order ||
                     this.Order.Equals(input.Order)
@@ -519,6 +576,11 @@ public override int GetHashCode()
                 {
                     hashCode = (hashCode * 59) + this.EventGlobalEmittersFilter.GetHashCode();
                 }
+                if (this.BalanceChangeResourcesFilter != null)
+                {
+                    hashCode = (hashCode * 59) + this.BalanceChangeResourcesFilter.GetHashCode();
+                }
+                hashCode = (hashCode * 59) + this.TransactionStatusFilter.GetHashCode();
                 hashCode = (hashCode * 59) + this.Order.GetHashCode();
                 if (this.OptIns != null)
                 {