Merge pull request #773 from radixdlt/native-res-kind

Added native resource details

.editorconfig

@@ -295,6 +295,7 @@ dotnet_diagnostic.SA1649.severity = none # SA1649FileNameMustMatchTypeName - it
 # > Inherited from other projects
 dotnet_diagnostic.SA0001.severity = none # SA0001XmlCommentAnalysisDisabled
 dotnet_diagnostic.SA1101.severity = none # SA1101PrefixLocalCallsWithThis
+dotnet_diagnostic.SA1118.severity = none # SA1118ParameterMustNotSpanMultipleLines - SQL queries
 dotnet_diagnostic.SA1124.severity = none # SA1124DoNotUseRegions
 dotnet_diagnostic.SA1129.severity = none # SA1129DoNotUseDefaultValueTypeConstructor - does not comply with the use of HashCode
 dotnet_diagnostic.SA1201.severity = none # SA1201ElementsMustAppearInTheCorrectOrder

CHANGELOG.md

@@ -15,16 +15,21 @@ Release built: _not released yet_
 - New `event_global_emitters_filter` filter added to `/stream/transactions` endpoint. It allows filtering transactions by the global ancestor of an event emitter. For events emitted by a global entity it is going to be that entity, for internal entities it is going to be a global ancestor.
 - Changed `variant_id` of `ProgrammaticScryptoSborValueEnum` from numeric (`type: integer`) to string-encoded numeric (`type: string`) to make it compatible with the rest of the ecosystem.
 - Optimized `/statistics/validators/uptime` endpoint processing time.
-- Added support for two-way linked dApps in the `/state/entity/details` endpoint.
-  - Brand-new `two_way_linked_*` properties on the `details` property of Resources, Accounts, Packages and other global components.
+- Added support for two-way linked dApps in the `/state/entity/details` endpoint, returned when the `dapp_two_way_links` opt-in is enabled.
+  - Brand-new `two_way_linked_*` properties on the `details` property of the Resources, Accounts, Packages and other global entities.
   - See https://docs.radixdlt.com/docs/metadata-for-verification#metadata-standards-for-verification-of-onledger-entities for detailed specification.
+- Added support for the Native Resource Details in the `/state/entity/details` endpoint, returned when the `native_resource_details` opt-in is enabled. 
+  - Brand-new `native_resource_details` property on the `details` property.
+  - Includes **unit** redemption value for the Validator LSU token and the unit tokens of various Pools. 
 
 ### Database changes
 - Replaced relationship-related columns (`*_entity_id`) in the `entities` table with more generic collection implementation using `correlated_entity_*` columns.
 - Replaced per-epoch validator emissions (`validator_emission_statistics` table) with their cumulative statistics (`validator_cumulative_emission_history` table).
 - Added `non_fungible_data_mutable_fields` to `entities` table. Which contains list of all mutable non fungible data fields for non fungible resource entities.
 - New `ledger_transaction_markers` type with the `event_global_emitter` discriminator. It represents the global emitter for each event.
-- Added new `unverified_standard_metadata_*` tables. They hold **some** of the metadata entries using db-friendly (normalized) model. See https://docs.radixdlt.com/docs/metadata-standards 
+- Added new `unverified_standard_metadata_*` tables. They hold **some** of the metadata entries using db-friendly (normalized) model. See https://docs.radixdlt.com/docs/metadata-standards
+- Extended list of supported entity correlations in the `entities` table.
+- Renamed values of the `entity_relationship` enum type. 
 
 ## 1.6.3
 Release built: 06.08.2024

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

@@ -66,16 +66,43 @@ namespace RadixDlt.NetworkGateway.Abstractions.Model;
 
 public enum EntityRelationship
 {
-    ComponentPackage,
-    ValidatorStakeVault,
-    ValidatorPendingXrdWithdrawVault,
-    ValidatorLockedOwnerStakeUnitVault,
-    ValidatorPendingOwnerStakeUnitUnlockVault,
-    VaultResource,
-    VaultRoyalty,
-    VaultResourcePool,
-    AccountLockerLocker,
-    AccountLockerAccount,
-    ResourcePoolUnit,
-    ResourcePoolResource,
+    // Components
+
+    ComponentToInstantiatingPackage,
+
+    // Vaults
+
+    VaultToResource,
+
+    RoyaltyVaultOfComponent,
+
+    // Validators
+
+    ValidatorToStakeVault,
+    ValidatorToPendingXrdWithdrawVault,
+    ValidatorToLockedOwnerStakeUnitVault,
+    ValidatorToPendingOwnerStakeUnitUnlockVault,
+
+    StakeVaultOfValidator,
+    ClaimTokenOfValidator,
+
+    // Account Lockers (used on related Vaults and KeyValueStores)
+
+    AccountLockerOfLocker,
+    AccountLockerOfAccount,
+
+    // Resource Pools (used on One-, Two- and Multi-Resource Pools)
+
+    ResourcePoolToUnitResource,
+    ResourcePoolToResource,
+    ResourcePoolToResourceVault,
+
+    UnitVaultOfResourcePool,
+    ResourceVaultOfResourcePool,
+
+    // Access Controllers
+
+    AccessControllerToRecoveryBadge,
+
+    RecoveryBadgeOfAccessController,
 }

src/RadixDlt.NetworkGateway.Abstractions/Numerics/TokenAmount.cs

@@ -156,7 +156,7 @@ public static TokenAmount FromDecimalString(string decimalString)
 
     public static TokenAmount operator *(TokenAmount a, TokenAmount b) => (a.IsNaN() || b.IsNaN()) ? NaN : new TokenAmount(a._subUnits * b._subUnits);
 
-    public static TokenAmount operator /(TokenAmount a, TokenAmount b) => (a.IsNaN() || b.IsNaN()) ? NaN : new TokenAmount(a._subUnits / b._subUnits);
+    public static TokenAmount operator /(TokenAmount a, TokenAmount b) => (a.IsNaN() || b.IsNaN()) ? NaN : Divide(a, b);
 
     // ReSharper disable SimplifyConditionalTernaryExpression - As it's clearer as written
 #pragma warning disable IDE0075
@@ -269,4 +269,42 @@ public int CompareTo(TokenAmount other)
         var isNaNComparison = _isNaN.CompareTo(other._isNaN);
         return isNaNComparison != 0 ? isNaNComparison : _subUnits.CompareTo(other._subUnits);
     }
+
+    // Heavily inspired by https://www.codeproject.com/Articles/5366079/BigDecimal-in-Csharp
+    // Licensed under CPOL: https://en.wikipedia.org/wiki/Code_Project_Open_License
+    // Author: Paulo Francisco Zemek. August, 01, 2023.
+    private static TokenAmount Divide(TokenAmount dividend, TokenAmount divisor)
+    {
+        if (divisor == Zero)
+        {
+            // This rule might look odd, but when simplifying expressions, x/x (x divided by x) is 1.
+            // So, to keep the rule true, 0 divided by 0 is also 1.
+            if (dividend == Zero)
+            {
+                return OneFullUnit;
+            }
+
+            throw new DivideByZeroException($"{nameof(divisor)} can only be zero if {nameof(dividend)} is zero.");
+        }
+
+        var doublePrecisionDividendSubUnits = dividend._subUnits * _divisor;
+        var divisorSubUnits = divisor._subUnits;
+
+        return FromSubUnits(doublePrecisionDividendSubUnits / divisorSubUnits);
+    }
+
+    // Is there a faster approach that works with BigIntegers?
+    // It seems Log10 isn't faster at all.
+    private static int CountDigits(BigInteger value)
+    {
+        int count = 0;
+
+        while (value > 0)
+        {
+            count++;
+            value /= 10;
+        }
+
+        return count;
+    }
 }

src/RadixDlt.NetworkGateway.Abstractions/StandardMetadata/ResolvedTwoWayLink.cs

@@ -66,17 +66,14 @@
 
 namespace RadixDlt.NetworkGateway.Abstractions.StandardMetadata;
 
-public abstract record ResolvedTwoWayLink(string? InvalidReason)
-{
-    public bool IsValid => InvalidReason == null;
-}
+public abstract record ResolvedTwoWayLink;
 
-public sealed record DappClaimedEntityResolvedTwoWayLink(EntityAddress EntityAddress, string? InvalidReason) : ResolvedTwoWayLink(InvalidReason);
+public sealed record DappClaimedEntityResolvedTwoWayLink(EntityAddress EntityAddress) : ResolvedTwoWayLink;
 
-public sealed record DappClaimedWebsiteResolvedTwoWayLink(Uri Origin, string? InvalidReason) : ResolvedTwoWayLink(InvalidReason);
+public sealed record DappClaimedWebsiteResolvedTwoWayLink(Uri Origin) : ResolvedTwoWayLink;
 
-public sealed record DappDefinitionResolvedTwoWayLink(EntityAddress EntityAddress, string? InvalidReason) : ResolvedTwoWayLink(InvalidReason);
+public sealed record DappDefinitionResolvedTwoWayLink(EntityAddress EntityAddress) : ResolvedTwoWayLink;
 
-public sealed record DappDefinitionsResolvedTwoWayLink(EntityAddress EntityAddress, string? InvalidReason) : ResolvedTwoWayLink(InvalidReason);
+public sealed record DappDefinitionsResolvedTwoWayLink(EntityAddress EntityAddress) : ResolvedTwoWayLink;
 
-public sealed record DappAccountLockerResolvedTwoWayLink(EntityAddress LockerAddress, string? InvalidReason) : ResolvedTwoWayLink(InvalidReason);
+public sealed record DappAccountLockerResolvedTwoWayLink(EntityAddress LockerAddress) : ResolvedTwoWayLink;

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

@@ -3968,6 +3968,7 @@ components:
           package_royalty_vault_balance: true
           non_fungible_include_nfids: true
           dapp_two_way_links: true
+          native_resource_details: true
           explicit_metadata:
             - name
             - description
@@ -4004,6 +4005,10 @@ components:
           description: if set to `true`, on-ledger dApp two-way links (resolved & verified) are returned. See https://docs.radixdlt.com/docs/metadata-for-verification for more details.
           type: boolean
           default: false
+        native_resource_details:
+          description: if set to `true`, additional details for the Network native resources are returned.
+          type: boolean
+          default: false
     StateEntityDetailsResponse:
       allOf:
         - $ref: "#/components/schemas/LedgerStateMixin"
@@ -4094,6 +4099,8 @@ components:
               $ref: "#/components/schemas/BigDecimal"
             two_way_linked_dapps:
               $ref: "#/components/schemas/TwoWayLinkedDappsCollection"
+            native_resource_details:
+              $ref: "#/components/schemas/NativeResourceDetails"
     StateEntityDetailsResponseNonFungibleResourceDetails:
       allOf:
         - $ref: "#/components/schemas/StateEntityDetailsResponseItemDetails"
@@ -4122,6 +4129,8 @@ components:
                 type: string
             two_way_linked_dapps:
               $ref: "#/components/schemas/TwoWayLinkedDappsCollection"
+            native_resource_details:
+              $ref: "#/components/schemas/NativeResourceDetails"
     StateEntityDetailsResponseFungibleVaultDetails:
       allOf:
         - $ref: "#/components/schemas/StateEntityDetailsResponseItemDetails"
@@ -4216,6 +4225,8 @@ components:
             two_way_linked_dapp_details:
               description: Two-way linked (resolved & verified) dApp details. Applicable to dApp definition accounts only and limited to on-ledger information only.
               $ref: "#/components/schemas/TwoWayLinkedDappOnLedgerDetails"
+            native_resource_details:
+              $ref: "#/components/schemas/NativeResourceDetails"
 
     StateAccountResourcePreferencesPageRequest:
       allOf:
@@ -5017,6 +5028,188 @@ components:
           items:
             type: string
 
+    #
+    # Native Resources
+    #
+
+    NativeResourceUnitRedemptionValue:
+      type: array
+      items:
+        $ref: "#/components/schemas/NativeResourceRedemptionValueItem"
+    NativeResourceRedemptionValueItem:
+      type: object
+      required:
+        - resource_address
+      properties:
+        resource_address:
+          $ref: "#/components/schemas/Address"
+        amount:
+          $ref: "#/components/schemas/BigDecimal"
+
+    NativeResourceKind:
+      type: string
+      enum:
+        - Xrd
+        - PackageOwnerBadge
+        - AccountOwnerBadge
+        - IdentityOwnerBadge
+        - ValidatorOwnerBadge
+        - Secp256k1SignatureResource
+        - Ed25519SignatureResource
+        - GlobalCallerResource
+        - PackageOfDirectCallerResource
+        - SystemExecutionResource
+        - ValidatorLiquidStakeUnit
+        - ValidatorClaimNft
+        - OneResourcePoolUnit
+        - TwoResourcePoolUnit
+        - MultiResourcePoolUnit
+        - AccessControllerRecoveryBadge
+    NativeResourceDetails:
+      type: object
+      discriminator:
+        propertyName: kind
+        mapping:
+          Xrd: "#/components/schemas/NativeResourceXrdValue"
+          PackageOwnerBadge: "#/components/schemas/NativeResourcePackageOwnerBadgeValue"
+          AccountOwnerBadge: "#/components/schemas/NativeResourceAccountOwnerBadgeValue"
+          IdentityOwnerBadge: "#/components/schemas/NativeResourceIdentityOwnerBadgeValue"
+          ValidatorOwnerBadge: "#/components/schemas/NativeResourceValidatorOwnerBadgeValue"
+          Secp256k1SignatureResource: "#/components/schemas/NativeResourceSecp256k1SignatureResourceValue"
+          Ed25519SignatureResource: "#/components/schemas/NativeResourceEd25519SignatureResourceValue"
+          GlobalCallerResource: "#/components/schemas/NativeResourceGlobalCallerResourceValue"
+          PackageOfDirectCallerResource: "#/components/schemas/NativeResourcePackageOfDirectCallerResourceValue"
+          SystemExecutionResource: "#/components/schemas/NativeResourceSystemExecutionResourceValue"
+          ValidatorLiquidStakeUnit: "#/components/schemas/NativeResourceValidatorLiquidStakeUnitValue"
+          ValidatorClaimNft: "#/components/schemas/NativeResourceValidatorClaimNftValue"
+          OneResourcePoolUnit: "#/components/schemas/NativeResourceOneResourcePoolUnitValue"
+          TwoResourcePoolUnit: "#/components/schemas/NativeResourceTwoResourcePoolUnitValue"
+          MultiResourcePoolUnit: "#/components/schemas/NativeResourceMultiResourcePoolUnitValue"
+          AccessControllerRecoveryBadge: "#/components/schemas/NativeResourceAccessControllerRecoveryBadgeValue"
+      required:
+        - kind
+      properties:
+        kind:
+          $ref: "#/components/schemas/NativeResourceKind"
+    NativeResourceXrdValue:
+      allOf:
+        - $ref: "#/components/schemas/NativeResourceDetails"
+        - type: object
+    NativeResourcePackageOwnerBadgeValue:
+      allOf:
+        - $ref: "#/components/schemas/NativeResourceDetails"
+        - type: object
+    NativeResourceAccountOwnerBadgeValue:
+      allOf:
+        - $ref: "#/components/schemas/NativeResourceDetails"
+        - type: object
+    NativeResourceIdentityOwnerBadgeValue:
+      allOf:
+        - $ref: "#/components/schemas/NativeResourceDetails"
+        - type: object
+    NativeResourceValidatorOwnerBadgeValue:
+      allOf:
+        - $ref: "#/components/schemas/NativeResourceDetails"
+        - type: object
+    NativeResourceSecp256k1SignatureResourceValue:
+      allOf:
+        - $ref: "#/components/schemas/NativeResourceDetails"
+        - type: object
+    NativeResourceEd25519SignatureResourceValue:
+      allOf:
+        - $ref: "#/components/schemas/NativeResourceDetails"
+        - type: object
+    NativeResourceGlobalCallerResourceValue:
+      allOf:
+        - $ref: "#/components/schemas/NativeResourceDetails"
+        - type: object
+    NativeResourcePackageOfDirectCallerResourceValue:
+      allOf:
+        - $ref: "#/components/schemas/NativeResourceDetails"
+        - type: object
+    NativeResourceSystemExecutionResourceValue:
+      allOf:
+        - $ref: "#/components/schemas/NativeResourceDetails"
+        - type: object
+    NativeResourceValidatorLiquidStakeUnitValue:
+      allOf:
+        - $ref: "#/components/schemas/NativeResourceDetails"
+        - type: object
+          required:
+            - validator_address
+            - redemption_resource_count
+            - unit_redemption_value
+          properties:
+            validator_address:
+              $ref: "#/components/schemas/Address"
+            redemption_resource_count:
+              type: integer
+            unit_redemption_value:
+              $ref: "#/components/schemas/NativeResourceUnitRedemptionValue"
+    NativeResourceValidatorClaimNftValue:
+      allOf:
+        - $ref: "#/components/schemas/NativeResourceDetails"
+        - type: object
+          required:
+            - validator_address
+          properties:
+            validator_address:
+              $ref: "#/components/schemas/Address"
+    NativeResourceOneResourcePoolUnitValue:
+      allOf:
+        - $ref: "#/components/schemas/NativeResourceDetails"
+        - type: object
+          required:
+            - pool_address
+            - redemption_resource_count
+            - unit_redemption_value
+          properties:
+            pool_address:
+              $ref: "#/components/schemas/Address"
+            redemption_resource_count:
+              type: integer
+            unit_redemption_value:
+              $ref: "#/components/schemas/NativeResourceUnitRedemptionValue"
+    NativeResourceTwoResourcePoolUnitValue:
+      allOf:
+        - $ref: "#/components/schemas/NativeResourceDetails"
+        - type: object
+          required:
+            - pool_address
+            - redemption_resource_count
+            - unit_redemption_value
+          properties:
+            pool_address:
+              $ref: "#/components/schemas/Address"
+            redemption_resource_count:
+              type: integer
+            unit_redemption_value:
+              $ref: "#/components/schemas/NativeResourceUnitRedemptionValue"
+    NativeResourceMultiResourcePoolUnitValue:
+      allOf:
+        - $ref: "#/components/schemas/NativeResourceDetails"
+        - type: object
+          required:
+            - pool_address
+            - redemption_resource_count
+            - unit_redemption_value
+          properties:
+            pool_address:
+              $ref: "#/components/schemas/Address"
+            redemption_resource_count:
+              type: integer
+            unit_redemption_value:
+              $ref: "#/components/schemas/NativeResourceUnitRedemptionValue"
+    NativeResourceAccessControllerRecoveryBadgeValue:
+      allOf:
+        - $ref: "#/components/schemas/NativeResourceDetails"
+        - type: object
+          required:
+            - access_controller_address
+          properties:
+            access_controller_address:
+              $ref: "#/components/schemas/Address"
+
     #
     # Metadata Typed Value
     #