Merge pull request #860 from multiversx/development

Development into main

docs/integrators/deep-history-squad.md

@@ -39,6 +39,23 @@ In the example above, the key `726573657276650000000a55544b2d326638306539` is de
 
 [comment]: # (mx-context-auto)
 
+## Historical VM queries
+
+Starting with the [Sirius Patch 5](https://github.com/multiversx/mx-chain-mainnet-config/releases/tag/v1.6.18.0), deep-history observers can resolve historical VM queries. Such a query specifies the `blockNonce` parameter:
+
+```
+POST http://localhost:8080/vm-values/query?blockNonce={...} HTTP/1.1
+Content-Type: application/json
+
+{
+  "scAddress": "...",
+  "funcName": "...",
+  "args": [ ... ]
+}
+```
+
+[comment]: # (mx-context-auto)
+
 ## MultiversX squad
 
 The observing squads backing the public Gateways, in addition to being full history squads (serving past blocks, transactions and events up until the Genesis), also act as 3-epochs deep-history squads. That is, for **mainnet**, one can use https://gateway.multiversx.com to resolve historical account (state) queries, for the last 3 days. This interval is driven by the configuration parameter `[StoragePruning.NumEpochsToKeep]`, which is set to `4`, by default.
@@ -101,11 +118,32 @@ Never attach a non-pruned database to a regular observer (i.e. that does not hav
 
 ## Downloading non-pruned database
 
-Archives supporting historical lookup are available to download from a Google Cloud Storage bucket.
+Archives supporting historical lookup are available to download from a Google Cloud Storage [bucket](https://console.cloud.google.com/storage/browser/multiversx-deep-history-archives-mainnet).
 
-:::important
-Documentation in this section is preliminary and subject to change.
-:::
+In order to avoid unintentional downloads and promote careful fetching of archives, we've enabled the [requester pays](https://cloud.google.com/storage/docs/requester-pays) feature on the bucket that holds the deep-history archives for mainnet.
+
+### Requirements
+
+1. **Google Cloud Platform Account**: An account on Google Cloud Platform with billing enabled is required. Find out how you can manage your billing account and modify your project here:
+- https://cloud.google.com/billing/docs/how-to/manage-billing-account
+- https://cloud.google.com/billing/docs/how-to/modify-project
+
+2. **Google Cloud SDK**: The Google Cloud SDK includes the `gcloud` command-line tool, which you'll use to interact with Google Cloud Storage. In order to install it, please follow the instructions provided on the [Google Cloud SDK webpage](https://cloud.google.com/sdk/docs/install).
+
+### Downloading archives
+
+Once you have the Google Cloud SDK installed and you're [authenticated](https://cloud.google.com/docs/authentication/gcloud), you can download archives from the Google Cloud Storage bucket using the `gcloud storage cp` command.
+
+Here's an example command that downloads an archive from the `multiversx-deep-history-archives-mainnet` bucket:
+```
+gcloud storage cp gs://multiversx-deep-history-archives-mainnet/shard-0/Epoch_00000.tar ~/DOWNLOAD_LOCATION --billing-project=BILLING_PROJECT
+```
+Replace **BILLING_PROJECT** with the name of your billing project and **~/DOWNLOAD_LOCATION** with the directory where the archives should be downloaded.
+
+The following example will download epochs starting with Epoch_01000.tar up to Epoch_01300.tar, for a billing project called **multiversx**:
+```
+gcloud storage cp gs://multiversx-deep-history-archives-mainnet/shard-0/Epoch_0{1000..1300}.tar ~/Downloads/ --billing-project=multiversx
+```
 
 [comment]: # (mx-context-auto)
 
@@ -289,29 +327,6 @@ Once the **import-db** is over, the `db` folder can be attached to a deep-histor
 
 [comment]: # (mx-context-auto)
 
-## Historical VM queries
-
-:::important
-Documentation in this section is preliminary and subject to change.
-:::
-
-Starting with the [Sirius Mainnet Upgrade](https://github.com/multiversx/mx-specs/blob/main/releases/protocol/release-specs-v1.6.0-Sirius.md), deep-history observers can resolve VM queries up to `[StoragePruning.NumActivePersisters]` (by default, 3) epochs in the past. Such a query specifies the `blockNonce` parameter:
-
-```
-POST http://localhost:8080/vm-values/query?blockNonce={...} HTTP/1.1
-Content-Type: application/json
-
-{
-  "scAddress": "...",
-  "funcName": "...",
-  "args": [ ... ]
-}
-```
-
-VM queries that refer older data aren't supported as of January 2024 (Sirius). This will be fixed in a future release.
-
-[comment]: # (mx-context-auto)
-
 ## Starting a squad
 
 Suppose you have prepared the data for a deep-history squad beforehand, whether by downloading it or by reconstructing it locally. Then, the deep-history data root folder should look as follows:

docs/sdk-and-tools/sdk-js/sdk-js-cookbook-v13.md

@@ -180,6 +180,19 @@ await Promise.all([
 ]);
 ```
 
+In some circumstances, when awaiting for a transaction completion in order to retrieve its logs and events,
+it's possible that these pieces of information are missing at the very moment the transaction is marked as completed -
+they may not be immediately available.
+
+If that is an issue, you can configure the [`TransactionWatcher`](https://multiversx.github.io/mx-sdk-js-core/v13/classes/TransactionWatcher.html) to have additional **patience**
+before returning the transaction object. Below, we're adding a patience of 8 seconds:
+
+```
+const watcherWithPatience = new TransactionWatcher(apiNetworkProvider, { patienceMilliseconds: 8000 });
+```
+
+Alternatively, use [`TransactionWatcher.awaitAnyEvent()`](https://multiversx.github.io/mx-sdk-js-core/v13/classes/TransactionWatcher.html#awaitAnyEvent) or [`TransactionWatcher.awaitOnCondition()`](https://multiversx.github.io/mx-sdk-js-core/v13/classes/TransactionWatcher.html#awaitOnCondition) to customize the waiting strategy.
+
 For a different awaiting strategy, also see [extending sdk-js](https://docs.multiversx.com/sdk-and-tools/sdk-js/extending-sdk-js).
 
 ## Token transfers
@@ -742,6 +755,36 @@ const parsedOutcome = parser.parseExecute({ transactionOutcome });
 console.log(parsedOutcome);
 ```
 
+### Decode transaction events
+
+Additionally, you might be interested into decoding the events emitted by a contract.
+You can do so by means of the [`TransactionEventsParser`](https://multiversx.github.io/mx-sdk-js-core/v13/classes/TransactionEventsParser.html).
+
+Suppose we'd like to decode a `startPerformAction` event emitted by the [**multisig**](https://github.com/multiversx/mx-contracts-rs/tree/main/contracts/multisig) contract.
+
+Let's fetch [a previously-processed transaction](https://devnet-explorer.multiversx.com/transactions/05d445cdd145ecb20374844dcc67f0b1e370b9aa28a47492402bc1a150c2bab4),
+to serve as an example, and convert it to a [`TransactionOutcome`](https://multiversx.github.io/mx-sdk-js-core/v13/classes/TransactionOutcome.html) (see above why):
+
+```
+const transactionOnNetworkMultisig = await apiNetworkProvider.getTransaction("05d445cdd145ecb20374844dcc67f0b1e370b9aa28a47492402bc1a150c2bab4");
+const transactionOutcomeMultisig = converter.transactionOnNetworkToOutcome(transactionOnNetworkMultisig);
+```
+
+Now, let's find and parse the event we are interested in:
+
+```
+import { TransactionEventsParser, findEventsByFirstTopic } from "@multiversx/sdk-core";
+
+const eventsParser = new TransactionEventsParser({
+    abi: abiMultisig
+});
+
+const [event] = findEventsByFirstTopic(transactionOutcomeMultisig, "startPerformAction");
+const parsedEvent = eventsParser.parseEvent({ event });
+
+console.log(parsedEvent);
+```
+
 ## Contract queries
 
 In order to perform Smart Contract queries, we recommend the use of [`SmartContractQueriesController`](https://multiversx.github.io/mx-sdk-js-core/v13/classes/SmartContractQueriesController.html).