Skip to content

Commit

Permalink
Merge pull request #855 from multiversx/v13-links
Browse files Browse the repository at this point in the history 
Add links to auto-generated docs
  • Loading branch information
@andreibancioiu
andreibancioiu authored Apr 3, 2024
2 parents d000a27 + 2711d97 commit 356298f
Showing 1 changed file with 31 additions and 31 deletions.
62 changes: 31 additions & 31 deletions docs/sdk-and-tools/sdk-js/sdk-js-cookbook-v13.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ console.log("Nonce:", alice.nonce);
```

:::note
Since `sdk-core v13`, the `Transaction` class exhibits its state as public read-write properties. For example, you can access and set the `nonce` property, instead of using `getNonce` and `setNonce`.
Since `sdk-core v13`, the [`Transaction`](https://multiversx.github.io/mx-sdk-js-core/v13/classes/Transaction.html) class exhibits its state as public read-write properties. For example, you can access and set the `nonce` property, instead of using `getNonce` and `setNonce`.
:::

If you are using `sdk-core v13` or later, use `tx.nonce = ` to apply the nonce to a transaction.
Expand All @@ -93,7 +93,7 @@ For further reference, please see [nonce management](https://docs.multiversx.com
### Preparing a simple transaction

:::note
Since `sdk-core v13`, the `Transaction` class exhibits its state as public read-write properties. For example, you can access and set the `nonce` property, instead of using `getNonce` and `setNonce`.
Since `sdk-core v13`, the [`Transaction`](https://multiversx.github.io/mx-sdk-js-core/v13/classes/Transaction.html) class exhibits its state as public read-write properties. For example, you can access and set the `nonce` property, instead of using `getNonce` and `setNonce`.
:::

```
Expand Down Expand Up @@ -157,7 +157,7 @@ const watcherUsingApi = new TransactionWatcher(apiNetworkProvider);
const transactionOnNetworkUsingApi = await watcherUsingApi.awaitCompleted(txHash);
```

If, instead, you use a `ProxyNetworkProvider` to instantiate the `TransactionWatcher`, you'll need to patch the `getTransaction` method,
If, instead, you use a `ProxyNetworkProvider` to instantiate the [`TransactionWatcher`](https://multiversx.github.io/mx-sdk-js-core/v13/classes/TransactionWatcher.html), you'll need to patch the `getTransaction` method,
so that it instructs the network provider to fetch the so-called _processing status_, as well (required by the watcher to detect transaction completion).

```
Expand All @@ -184,27 +184,27 @@ For a different awaiting strategy, also see [extending sdk-js](https://docs.mult

## Token transfers

Generally speaking, in order to create transactions that transfer native tokens or ESDT tokens, one should use the `TransferTransactionsFactory` class.
Generally speaking, in order to create transactions that transfer native tokens or ESDT tokens, one should use the [`TransferTransactionsFactory`](https://multiversx.github.io/mx-sdk-js-core/v13/classes/TransferTransactionsFactory.html) class.

:::note
In `sdk-core v13`, the `TransferTransactionsFactory` class was extended with new methods,
In `sdk-core v13`, the [`TransferTransactionsFactory`](https://multiversx.github.io/mx-sdk-js-core/v13/classes/TransferTransactionsFactory.html) class was extended with new methods,
to be aligned with the [SDKs specs](https://github.com/multiversx/mx-sdk-specs/blob/main/core/transactions-factories/transfer_transactions_factory.md).
The old, legacy methods are still available (see below), thus existing client code isn't affected.
:::

:::note
In `sdk-core v13`, the `TokenTransfer` class has changed, in a non-breaking manner.
In `sdk-core v13`, the [`TokenTransfer`](https://multiversx.github.io/mx-sdk-js-core/v13/classes/TokenTransfer.html) class has changed, in a non-breaking manner.
Though, from now on, it should only be used for prepairing ESDT token transfers, not native EGLD transfers.

A `TokenTransfer` object can still be instantiated using the legacy methods, e.g. `fungibleFromAmount`, `nonFungible` (which are still available),
A [`TokenTransfer`](https://multiversx.github.io/mx-sdk-js-core/v13/classes/TokenTransfer.html) object can still be instantiated using the legacy methods, e.g. `fungibleFromAmount`, `nonFungible` (which are still available),
but we recommend using the new approach instead (which, among others, makes abstraction of the number of decimals a token has).
:::

:::tip
For formatting or parsing token amounts, see [formatting and parsing amounts](#formatting-and-parsing-amounts).
:::

First, let's create a `TransferTransactionsFactory`:
First, let's create a [`TransferTransactionsFactory`](https://multiversx.github.io/mx-sdk-js-core/v13/classes/TransferTransactionsFactory.html):

```
import { Token, TokenTransfer, TransactionsFactoryConfig, TransferTransactionsFactory } from "@multiversx/sdk-core";
Expand Down Expand Up @@ -429,12 +429,12 @@ const code = Code.fromBuffer(codeBuffer);

In `sdk-core v13`, the recommended way to create transactions for deploying
(and, for that matter, upgrading and interacting with)
smart contracts is through a `SmartContractTransactionsFactory`.
smart contracts is through a [`SmartContractTransactionsFactory`](https://multiversx.github.io/mx-sdk-js-core/v13/classes/SmartContractTransactionsFactory.html).

The older (legacy) approach, using the method `SmartContract.deploy()`, is still available, however.
At some point in the future, `SmartContract.deploy()` will be deprecated and removed.
The older (legacy) approach, using the method [`SmartContract.deploy()`](https://multiversx.github.io/mx-sdk-js-core/v13/classes/SmartContract.html#deploy), is still available, however.
At some point in the future, [`SmartContract.deploy()`](https://multiversx.github.io/mx-sdk-js-core/v13/classes/SmartContract.html#deploy) will be deprecated and removed.

Now, let's create a `SmartContractTransactionsFactory`:
Now, let's create a [`SmartContractTransactionsFactory`](https://multiversx.github.io/mx-sdk-js-core/v13/classes/SmartContractTransactionsFactory.html):

```
import { SmartContractTransactionsFactory, TransactionsFactoryConfig } from "@multiversx/sdk-core";
Expand All @@ -460,7 +460,7 @@ Now, prepare the deploy transaction:
```
import { U32Value } from "@multiversx/sdk-core";
// For deploy arguments, use `TypedValue` objects if you haven't provided an ABI to the factory:
// For deploy arguments, use [`TypedValue`](https://multiversx.github.io/mx-sdk-js-core/v13/classes/TypedValue.html) objects if you haven't provided an ABI to the factory:
let args = [new U32Value(42)];
// Or use simple, plain JavaScript values and objects if you have provided an ABI to the factory:
args = [42];
Expand All @@ -474,10 +474,10 @@ const deployTransaction = factory.createTransactionForDeploy({
```

:::tip
When creating transactions using `SmartContractTransactionsFactory`, even if the ABI is available and provided,
you can still use `TypedValue` objects as arguments for deployments and interactions.
When creating transactions using [`SmartContractTransactionsFactory`](https://multiversx.github.io/mx-sdk-js-core/v13/classes/SmartContractTransactionsFactory.html), even if the ABI is available and provided,
you can still use [`TypedValue`](https://multiversx.github.io/mx-sdk-js-core/v13/classes/TypedValue.html) objects as arguments for deployments and interactions.

Even further, you can use a mix of `TypedValue` objects and plain JavaScript values and objects. For example:
Even further, you can use a mix of [`TypedValue`](https://multiversx.github.io/mx-sdk-js-core/v13/classes/TypedValue.html) objects and plain JavaScript values and objects. For example:
```
let args = [new U32Value(42), "hello", { foo: "bar" }, new TokenIdentifierValue("TEST-abcdef")];
```
Expand Down Expand Up @@ -535,10 +535,10 @@ console.log("Contract address:", contractAddress.bech32());

In the end, you can parse the results using a [`SmartContractTransactionsOutcomeParser`](https://multiversx.github.io/mx-sdk-js-core/v13/classes/SmartContractTransactionsOutcomeParser.html).
However, since the `parseDeploy` method requires a [`TransactionOutcome`](https://multiversx.github.io/mx-sdk-js-core/v13/classes/TransactionOutcome.html) object as input,
we need to first convert our `TransactionOnNetwork` object to a `TransactionOutcome`, by means of a [`TransactionsConverter`](https://multiversx.github.io/mx-sdk-js-core/v13/classes/TransactionsConverter.html).
we need to first convert our `TransactionOnNetwork` object to a [`TransactionOutcome`](https://multiversx.github.io/mx-sdk-js-core/v13/classes/TransactionOutcome.html), by means of a [`TransactionsConverter`](https://multiversx.github.io/mx-sdk-js-core/v13/classes/TransactionsConverter.html).

:::important
Generally speaking, the components of `sdk-core` and `sdk-network-providers` have different concerns.
Generally speaking, the components of `sdk-core` and `sdk-network-providers` have different concerns.
The former aims to be agnostic to network providers, while the latter is designed to cover specifics of [the available REST APIs](https://docs.multiversx.com/sdk-and-tools/rest-api).

This being said, a certain impedance mismatch is expected between the two packages. This is resolved by means of specially crafted _converters_ and _adapters_.
Expand All @@ -562,13 +562,13 @@ console.log(parsedOutcome);

In `sdk-core v13`, the recommended way to create transactions for calling
(and, for that matter, deploying and upgrading)
smart contracts is through a `SmartContractTransactionsFactory`.
smart contracts is through a [`SmartContractTransactionsFactory`](https://multiversx.github.io/mx-sdk-js-core/v13/classes/SmartContractTransactionsFactory.html).

The older (legacy) approaches, using `SmartContract.call()`, `SmartContract.methods.myFunction()`, `SmartContract.methodsExplicit.myFunction()` and
`new Interaction(contract, "myFunction", args)` are still available.
However, at some point in the (more distant) future, they will be deprecated and removed.

Now, let's create a `SmartContractTransactionsFactory`:
Now, let's create a [`SmartContractTransactionsFactory`](https://multiversx.github.io/mx-sdk-js-core/v13/classes/SmartContractTransactionsFactory.html):

```
import { SmartContractTransactionsFactory, TransactionsFactoryConfig } from "@multiversx/sdk-core";
Expand Down Expand Up @@ -597,7 +597,7 @@ previously deployed smart contract:
```
import { U32Value } from "@multiversx/sdk-core";
// For arguments, use `TypedValue` objects if you haven't provided an ABI to the factory:
// For arguments, use [`TypedValue`](https://multiversx.github.io/mx-sdk-js-core/v13/classes/TypedValue.html) objects if you haven't provided an ABI to the factory:
let args = [new U32Value(42)];
// Or use simple, plain JavaScript values and objects if you have provided an ABI to the factory:
args = [42];
Expand All @@ -612,10 +612,10 @@ const transaction = factory.createTransactionForExecute({
```

:::tip
When creating transactions using `SmartContractTransactionsFactory`, even if the ABI is available and provided,
you can still use `TypedValue` objects as arguments for deployments and interactions.
When creating transactions using [`SmartContractTransactionsFactory`](https://multiversx.github.io/mx-sdk-js-core/v13/classes/SmartContractTransactionsFactory.html), even if the ABI is available and provided,
you can still use [`TypedValue`](https://multiversx.github.io/mx-sdk-js-core/v13/classes/TypedValue.html) objects as arguments for deployments and interactions.

Even further, you can use a mix of `TypedValue` objects and plain JavaScript values and objects. For example:
Even further, you can use a mix of [`TypedValue`](https://multiversx.github.io/mx-sdk-js-core/v13/classes/TypedValue.html) objects and plain JavaScript values and objects. For example:
```
let args = [new U32Value(42), "hello", { foo: "bar" }, new TokenIdentifierValue("TEST-abcdef")];
```
Expand Down Expand Up @@ -711,7 +711,7 @@ const transactionWithMultipleTokenTransfers = factory.createTransactionForExecut
});
```

Above, we've prepared the `TokenTransfer` objects as seen in the section [token transfers](#token-transfers).
Above, we've prepared the [`TokenTransfer`](https://multiversx.github.io/mx-sdk-js-core/v13/classes/TokenTransfer.html) objects as seen in the section [token transfers](#token-transfers).

### Parsing transaction outcome

Expand Down Expand Up @@ -744,10 +744,10 @@ console.log(parsedOutcome);

## Contract queries

In order to perform Smart Contract queries, we recommend the use of `SmartContractQueriesController`.
The legacy approaches that rely on `SmartContract.createQuery()` or `Interaction.buildQuery()` are still available, but they will be deprecated in the (distant) future.
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).
The legacy approaches that rely on [`SmartContract.createQuery()`](https://multiversx.github.io/mx-sdk-js-core/v13/classes/SmartContract.html#createQuery) or [`Interaction.buildQuery()`](https://multiversx.github.io/mx-sdk-js-core/v13/classes/Interaction.html#buildQuery) are still available, but they will be deprecated in the (distant) future.

You will notice that the `SmartContractQueriesController` requires a `QueryRunner` object at initialization.
You will notice that the [`SmartContractQueriesController`](https://multiversx.github.io/mx-sdk-js-core/v13/classes/SmartContractQueriesController.html) requires a `QueryRunner` object at initialization.
A `NetworkProvider`, slighly adapted, is used to satisfy this requirement.

:::important
Expand All @@ -766,15 +766,15 @@ const queryRunner = new QueryRunnerAdapter({
networkProvider: apiNetworkProvider
});
let controller = new SmartContractQueriesController({
let controller = new SmartContractQueriesController({
queryRunner: queryRunner
});
```

If the contract ABI is available, provide it to the controller:

```
controller = new SmartContractQueriesController({
controller = new SmartContractQueriesController({
queryRunner: queryRunner,
abi: abi
});
Expand All @@ -790,7 +790,7 @@ const query = controller.createQuery({
});
```

Then, run the query against the network. You will get a `SmartContractQueryResponse` object.
Then, run the query against the network. You will get a [`SmartContractQueryResponse`](https://multiversx.github.io/mx-sdk-js-core/v13/classes/SmartContractQueryResponse.html) object.

```
const response = await controller.runQuery(query);
Expand Down

0 comments on commit 356298f

Please sign in to comment.