Merge pull request #366 from radixdlt/tweaks/rcnet-v2-docs

Tweaks/rcnet v2 docs

CHANGELOG.md

@@ -1,5 +1,46 @@
-## 0.4.0 - RCNet-V2
-_Release Date: Unreleased_
+# 0.4.0 - RCNet v2
+Release Date: 26.07.2023
+
+## RCNet v1 to RCNet v2 Migration Guide
+### What’s New?
+
+* Some properties are now annotated with an `is_locked` field indicating whether the value is locked or is still able to be updated.
+* Strongly-typed metadata values. Each metadata property is now represented as raw SBOR value and one of sixteen possible typed values, as per the [Entity Metadata docs](https://docs-babylon.radixdlt.com/main/scrypto/system/entity-metadata.html)
+* Additional entity details are returned from the `/state/entity/details` endpoint:
+  * Entity Role Assignments "access rules"
+    * _NOTE: Expect minor field renames at RCnet v3, to better align with the new role abstractions._
+  * Total supply alongside overall number of minted and burned tokens for resources.
+    * _WARNING: Total supply is not currently accurate. This will be fixed at RCnet v3._
+  * Package code, blueprints, schemas and royalty vaults
+* New opt-in flags are supported for `/state/entity/details` endpoint:
+  * `explicit_metadata` - allows to specify a collection of metadata keys you’d like to receive in the response,
+  * `ancestor_identities` - to include parental entity identifiers,
+  * `component_royalty_vault_valance` and `package_royalty_vault_balance` - to include royalty vaults and their respective balances where applicable,
+  * `non_fungible_include_nfids` - to include a first chunk of NFIDs of a returned NF vaults.
+* New opt-in flags supported for `/stream/transactions` endpoint:
+  * `raw_hex` to include raw bytes of a TX,
+  * `receipt_state_changes` to include low-level state changes,
+  * `receipt_fee_sumary` to include TX fees,
+  * `receipt_events` to include low-level events,
+  * `affected_global_entities` to include list of entities affected by given TX,
+* Additional transaction details in `/stream/transactions` endpoint: epoch, round, round_timestamp.
+* New filters in `/stream/transactions` endpoint to limit search results:
+  * `manifest_accounts_withdrawn_from_filter` - filter for TXs where given accounts have been withdrawn from,
+  * `manifest_accounts_deposited_into_filter` - filter for TXs where given accounts have been deposited into,
+  * `manifest_resources_filter` - filter for TXs where given resources have been used,
+  * `affected_global_entities_filter` - filter for TXs where given entities have had internal updates,
+  * `events_filter` - filter for TXs where the given event occurred (only Vault Deposit/Withdrawal events are currently supported)
+
+* More validator details in `/state/validators/list` endpoint: `state_vault`, `pending_xrd_withdraw_vault`, `locked_owner_stake_unit_vault`, `pending_owner_stake_unit_unlock_vault`
+
+### Breaking Changes
+
+* All addresses (including internal addresses) are now represented with a single Address type.
+* No more `as_string` and `as_string_collection` metadata representations - they’ve been replaced with strongly-typed models.
+* Minor property renames to reflect changes in upstream engine and Core APIs
+
+## Full technical changelog by minor release
+### 0.4.0
 
 - Renamed `mutable_data` property to `data` in `/state/non-fungible/data` endpoint.
 - Opt-in properties added to `/transaction/committed-details`,`/state/entity/details` user can specify additional properties in response.
@@ -29,8 +70,8 @@ _Release Date: Unreleased_
 
 - Fix `/state/non-fungible/data` to return data for all NFIDs
 
-## 0.3.0 - RCNet-V1
-_Release Date: 31.03.2023_
+# 0.3.0 - RCNet v1
+Release Date: 31.03.2023
 
 - `/entity/overview` and `/entity/details` endpoints replaced with single `/state/entity/details`.
 - Fungible and non-fungible resources are now ordered by the most recently updated.
@@ -45,8 +86,8 @@ _Release Date: 31.03.2023_
 - `/transaction/committed-details` endpoint operates on `intent_hash_hex` only now
 
 
-## 0.1.1 - Betanet V2
-_Release Date: 14.02.2023_
+# 0.1.1 - Betanet v2
+Release Date: 14.02.2023
 
 - Added `/state/validators/list` endpoint: returns paginable collection of all validators ever observed; validators that are part of so called active-set (i.e. participate in consensus for current/requested epoch) are decorated with some extra information like their public_key and stake.
 - `NonFungibleIdType`s `u32` and `u64` have been replaced with single `Number`.
@@ -59,15 +100,3 @@ Fixes for the following issues:
 - Incorrect calculation of balances when there are multiple vaults in a component. (Note - NFIds are still incorrectly tracked if spread across multiple vaults - this will be fixed as part of a schema overhaul)
 - Fungible resource metadata is updated properly
 
-
-## 0.1.0 - Betanet V1
-_Release Date: 20.12.2022_
-
-## 0.0.3
-_Release Date: 17.11.2022_
-
-## 0.0.2
-_Release Date: 14.11.2022_
-
-## 0.0.1 - Alphanet
-_Release Date: 24.10.2022_

README.md

@@ -9,7 +9,11 @@ The system is in three main parts:
 
 ## Using the Gateway API
 
-For documentation on the Gateway API, see the [RCNet-V1 Gateway API docs on ReDocly](https://radix-rcnet-v1-gateway.redoc.ly/).
+For documentation on the Gateway API, see the [RCNet V2 Gateway API docs on ReDocly](https://radix-rcnet-v2-gateway.redoc.ly/).
+
+### Known Issues
+
+* The returned total supply, minted and burned quantities are not accurate. This will be fixed at RCNet v3.
 
 ## Technical Docs
 

deployment/ci.env

@@ -1,4 +1,4 @@
 # Git commit version of most recent Node compatible with this Network Gateway (only used in CI/CD environments)
-FULLNODE_COMMIT=2f6c8786181c54c295060390a674929356e4e055
-FULLNODE_VERSION=rcnet-v2-phase2-r1
+FULLNODE_COMMIT=0de37b6d7fb59d1172908876e27648c3b9784dc3
+FULLNODE_VERSION=rcnet-v2-phase2-r4
 POSTGRES_VERSION=14.3.0

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

@@ -22,12 +22,16 @@ info:
     This document is an API reference documentation, visit [User Guide](https://docs-babylon.radixdlt.com/) to learn more
     about how to run a Gateway of your own.
 
+    ## Migration guide
+
+    Please see [the latest release notes](https://github.com/radixdlt/babylon-gateway/releases).
+
     ## Integration and forward compatibility guarantees
 
     We give no guarantees that other endpoints will not change before Babylon mainnet launch, although changes are expected to
     be minimal.
 servers:
-  - url: https://rcnet.radixdlt.com
+  - url: https://rcnet-v2.radixdlt.com
 x-tagGroups:
   - name: Overview
     tags:

src/RadixDlt.NetworkGateway.GatewayApiSdk/generated/Api/StateApi.cs

@@ -65,7 +65,7 @@
 /*
  * Babylon Gateway API - RCnet V2
  *
- * This API is exposed by the Babylon Radix Gateway to enable clients to efficiently query current and historic state on the RadixDLT ledger, and intelligently handle transaction submission.  It is designed for use by wallets and explorers. For simple use cases, you can typically use the Core API on a Node. A Gateway is only needed for reading historic snapshots of ledger states or a more robust set-up.  The Gateway API is implemented by the [Network Gateway](https://github.com/radixdlt/babylon-gateway), which is configured to read from [full node(s)](https://github.com/radixdlt/babylon-node) to extract and index data from the network.  This document is an API reference documentation, visit [User Guide](https://docs-babylon.radixdlt.com/) to learn more about how to run a Gateway of your own.  ## Integration and forward compatibility guarantees  We give no guarantees that other endpoints will not change before Babylon mainnet launch, although changes are expected to be minimal. 
+ * This API is exposed by the Babylon Radix Gateway to enable clients to efficiently query current and historic state on the RadixDLT ledger, and intelligently handle transaction submission.  It is designed for use by wallets and explorers. For simple use cases, you can typically use the Core API on a Node. A Gateway is only needed for reading historic snapshots of ledger states or a more robust set-up.  The Gateway API is implemented by the [Network Gateway](https://github.com/radixdlt/babylon-gateway), which is configured to read from [full node(s)](https://github.com/radixdlt/babylon-node) to extract and index data from the network.  This document is an API reference documentation, visit [User Guide](https://docs-babylon.radixdlt.com/) to learn more about how to run a Gateway of your own.  ## Migration guide  Please see [the latest release notes](https://github.com/radixdlt/babylon-gateway/releases).  ## Integration and forward compatibility guarantees  We give no guarantees that other endpoints will not change before Babylon mainnet launch, although changes are expected to be minimal. 
  *
  * The version of the OpenAPI document: 0.4.0
  * Generated by: https://github.com/openapitools/openapi-generator.git

src/RadixDlt.NetworkGateway.GatewayApiSdk/generated/Api/StatusApi.cs

@@ -65,7 +65,7 @@
 /*
  * Babylon Gateway API - RCnet V2
  *
- * This API is exposed by the Babylon Radix Gateway to enable clients to efficiently query current and historic state on the RadixDLT ledger, and intelligently handle transaction submission.  It is designed for use by wallets and explorers. For simple use cases, you can typically use the Core API on a Node. A Gateway is only needed for reading historic snapshots of ledger states or a more robust set-up.  The Gateway API is implemented by the [Network Gateway](https://github.com/radixdlt/babylon-gateway), which is configured to read from [full node(s)](https://github.com/radixdlt/babylon-node) to extract and index data from the network.  This document is an API reference documentation, visit [User Guide](https://docs-babylon.radixdlt.com/) to learn more about how to run a Gateway of your own.  ## Integration and forward compatibility guarantees  We give no guarantees that other endpoints will not change before Babylon mainnet launch, although changes are expected to be minimal. 
+ * This API is exposed by the Babylon Radix Gateway to enable clients to efficiently query current and historic state on the RadixDLT ledger, and intelligently handle transaction submission.  It is designed for use by wallets and explorers. For simple use cases, you can typically use the Core API on a Node. A Gateway is only needed for reading historic snapshots of ledger states or a more robust set-up.  The Gateway API is implemented by the [Network Gateway](https://github.com/radixdlt/babylon-gateway), which is configured to read from [full node(s)](https://github.com/radixdlt/babylon-node) to extract and index data from the network.  This document is an API reference documentation, visit [User Guide](https://docs-babylon.radixdlt.com/) to learn more about how to run a Gateway of your own.  ## Migration guide  Please see [the latest release notes](https://github.com/radixdlt/babylon-gateway/releases).  ## Integration and forward compatibility guarantees  We give no guarantees that other endpoints will not change before Babylon mainnet launch, although changes are expected to be minimal. 
  *
  * The version of the OpenAPI document: 0.4.0
  * Generated by: https://github.com/openapitools/openapi-generator.git

src/RadixDlt.NetworkGateway.GatewayApiSdk/generated/Api/StreamApi.cs

@@ -65,7 +65,7 @@
 /*
  * Babylon Gateway API - RCnet V2
  *
- * This API is exposed by the Babylon Radix Gateway to enable clients to efficiently query current and historic state on the RadixDLT ledger, and intelligently handle transaction submission.  It is designed for use by wallets and explorers. For simple use cases, you can typically use the Core API on a Node. A Gateway is only needed for reading historic snapshots of ledger states or a more robust set-up.  The Gateway API is implemented by the [Network Gateway](https://github.com/radixdlt/babylon-gateway), which is configured to read from [full node(s)](https://github.com/radixdlt/babylon-node) to extract and index data from the network.  This document is an API reference documentation, visit [User Guide](https://docs-babylon.radixdlt.com/) to learn more about how to run a Gateway of your own.  ## Integration and forward compatibility guarantees  We give no guarantees that other endpoints will not change before Babylon mainnet launch, although changes are expected to be minimal. 
+ * This API is exposed by the Babylon Radix Gateway to enable clients to efficiently query current and historic state on the RadixDLT ledger, and intelligently handle transaction submission.  It is designed for use by wallets and explorers. For simple use cases, you can typically use the Core API on a Node. A Gateway is only needed for reading historic snapshots of ledger states or a more robust set-up.  The Gateway API is implemented by the [Network Gateway](https://github.com/radixdlt/babylon-gateway), which is configured to read from [full node(s)](https://github.com/radixdlt/babylon-node) to extract and index data from the network.  This document is an API reference documentation, visit [User Guide](https://docs-babylon.radixdlt.com/) to learn more about how to run a Gateway of your own.  ## Migration guide  Please see [the latest release notes](https://github.com/radixdlt/babylon-gateway/releases).  ## Integration and forward compatibility guarantees  We give no guarantees that other endpoints will not change before Babylon mainnet launch, although changes are expected to be minimal. 
  *
  * The version of the OpenAPI document: 0.4.0
  * Generated by: https://github.com/openapitools/openapi-generator.git

src/RadixDlt.NetworkGateway.GatewayApiSdk/generated/Api/TransactionApi.cs

@@ -65,7 +65,7 @@
 /*
  * Babylon Gateway API - RCnet V2
  *
- * This API is exposed by the Babylon Radix Gateway to enable clients to efficiently query current and historic state on the RadixDLT ledger, and intelligently handle transaction submission.  It is designed for use by wallets and explorers. For simple use cases, you can typically use the Core API on a Node. A Gateway is only needed for reading historic snapshots of ledger states or a more robust set-up.  The Gateway API is implemented by the [Network Gateway](https://github.com/radixdlt/babylon-gateway), which is configured to read from [full node(s)](https://github.com/radixdlt/babylon-node) to extract and index data from the network.  This document is an API reference documentation, visit [User Guide](https://docs-babylon.radixdlt.com/) to learn more about how to run a Gateway of your own.  ## Integration and forward compatibility guarantees  We give no guarantees that other endpoints will not change before Babylon mainnet launch, although changes are expected to be minimal. 
+ * This API is exposed by the Babylon Radix Gateway to enable clients to efficiently query current and historic state on the RadixDLT ledger, and intelligently handle transaction submission.  It is designed for use by wallets and explorers. For simple use cases, you can typically use the Core API on a Node. A Gateway is only needed for reading historic snapshots of ledger states or a more robust set-up.  The Gateway API is implemented by the [Network Gateway](https://github.com/radixdlt/babylon-gateway), which is configured to read from [full node(s)](https://github.com/radixdlt/babylon-node) to extract and index data from the network.  This document is an API reference documentation, visit [User Guide](https://docs-babylon.radixdlt.com/) to learn more about how to run a Gateway of your own.  ## Migration guide  Please see [the latest release notes](https://github.com/radixdlt/babylon-gateway/releases).  ## Integration and forward compatibility guarantees  We give no guarantees that other endpoints will not change before Babylon mainnet launch, although changes are expected to be minimal. 
  *
  * The version of the OpenAPI document: 0.4.0
  * Generated by: https://github.com/openapitools/openapi-generator.git

src/RadixDlt.NetworkGateway.GatewayApiSdk/generated/Client/ApiClient.cs

@@ -65,7 +65,7 @@
 /*
  * Babylon Gateway API - RCnet V2
  *
- * This API is exposed by the Babylon Radix Gateway to enable clients to efficiently query current and historic state on the RadixDLT ledger, and intelligently handle transaction submission.  It is designed for use by wallets and explorers. For simple use cases, you can typically use the Core API on a Node. A Gateway is only needed for reading historic snapshots of ledger states or a more robust set-up.  The Gateway API is implemented by the [Network Gateway](https://github.com/radixdlt/babylon-gateway), which is configured to read from [full node(s)](https://github.com/radixdlt/babylon-node) to extract and index data from the network.  This document is an API reference documentation, visit [User Guide](https://docs-babylon.radixdlt.com/) to learn more about how to run a Gateway of your own.  ## Integration and forward compatibility guarantees  We give no guarantees that other endpoints will not change before Babylon mainnet launch, although changes are expected to be minimal. 
+ * This API is exposed by the Babylon Radix Gateway to enable clients to efficiently query current and historic state on the RadixDLT ledger, and intelligently handle transaction submission.  It is designed for use by wallets and explorers. For simple use cases, you can typically use the Core API on a Node. A Gateway is only needed for reading historic snapshots of ledger states or a more robust set-up.  The Gateway API is implemented by the [Network Gateway](https://github.com/radixdlt/babylon-gateway), which is configured to read from [full node(s)](https://github.com/radixdlt/babylon-node) to extract and index data from the network.  This document is an API reference documentation, visit [User Guide](https://docs-babylon.radixdlt.com/) to learn more about how to run a Gateway of your own.  ## Migration guide  Please see [the latest release notes](https://github.com/radixdlt/babylon-gateway/releases).  ## Integration and forward compatibility guarantees  We give no guarantees that other endpoints will not change before Babylon mainnet launch, although changes are expected to be minimal. 
  *
  * The version of the OpenAPI document: 0.4.0
  * Generated by: https://github.com/openapitools/openapi-generator.git

src/RadixDlt.NetworkGateway.GatewayApiSdk/generated/Client/ApiException.cs

@@ -65,7 +65,7 @@
 /*
  * Babylon Gateway API - RCnet V2
  *
- * This API is exposed by the Babylon Radix Gateway to enable clients to efficiently query current and historic state on the RadixDLT ledger, and intelligently handle transaction submission.  It is designed for use by wallets and explorers. For simple use cases, you can typically use the Core API on a Node. A Gateway is only needed for reading historic snapshots of ledger states or a more robust set-up.  The Gateway API is implemented by the [Network Gateway](https://github.com/radixdlt/babylon-gateway), which is configured to read from [full node(s)](https://github.com/radixdlt/babylon-node) to extract and index data from the network.  This document is an API reference documentation, visit [User Guide](https://docs-babylon.radixdlt.com/) to learn more about how to run a Gateway of your own.  ## Integration and forward compatibility guarantees  We give no guarantees that other endpoints will not change before Babylon mainnet launch, although changes are expected to be minimal. 
+ * This API is exposed by the Babylon Radix Gateway to enable clients to efficiently query current and historic state on the RadixDLT ledger, and intelligently handle transaction submission.  It is designed for use by wallets and explorers. For simple use cases, you can typically use the Core API on a Node. A Gateway is only needed for reading historic snapshots of ledger states or a more robust set-up.  The Gateway API is implemented by the [Network Gateway](https://github.com/radixdlt/babylon-gateway), which is configured to read from [full node(s)](https://github.com/radixdlt/babylon-node) to extract and index data from the network.  This document is an API reference documentation, visit [User Guide](https://docs-babylon.radixdlt.com/) to learn more about how to run a Gateway of your own.  ## Migration guide  Please see [the latest release notes](https://github.com/radixdlt/babylon-gateway/releases).  ## Integration and forward compatibility guarantees  We give no guarantees that other endpoints will not change before Babylon mainnet launch, although changes are expected to be minimal. 
  *
  * The version of the OpenAPI document: 0.4.0
  * Generated by: https://github.com/openapitools/openapi-generator.git