Add call and callView how-to

docs/build/isc/v1.0.0-rc.6/docs/how-tos/core-contracts/call-view.md

@@ -0,0 +1,96 @@
+---
+description: With call and callView you can interact with any core contract
+image: /img/logo/WASP_logo_dark.png
+tags:
+  - magic contract
+  - core
+  - EVM
+  - Ethereum
+  - Solidity
+  - ISC
+---
+
+# Interact with any Core contract
+
+## About `call` and `callView`
+
+The magic contract provides you with a solidity interface to the core contracts. Some functions like [`getL2BalanceBaseTokens`](../../reference/magic-contract/ISCAccounts.md#getl2balancebasetokens) are wrapped in the magic contract directly, others you need to call yourself. You can do that with the [`call`](../../reference/magic-contract/ISCSandbox.md#call) and [`callView`](../../reference/magic-contract/ISCSandbox.md#callview) functions.
+
+:::info WASM
+
+You can also use `call` and `callView` to interact with WASM contracts.
+
+:::
+
+## Example Code
+
+1. Get the [`AgentID`](../../explanations/how-accounts-work.md) from the sender by calling ISC.sandbox.getSenderAccount().
+
+```solidity
+ISCAgentID memory agentID = ISC.sandbox.getSenderAccount();
+```
+
+2. Initialize the parameters for the call by creating a new [`ISCDict`](../../reference/magic-contract/ISCTypes.md#iscdict). As you can see in the docs, [`getl2balancenativetokens`](../../reference/magic-contract/ISCAccounts.md#getl2balancenativetokens) takes two parameters.: the Agent ID and the native token ID. So, you have to create a dictionary with two key-value pairs. The key of the first pair (Agent ID) has to be `a` and the key for the second pair (native token ID) `N`.
+
+```solidity
+ISCDict memory params = ISCDict(new ISCDictItem[](2));
+params.items[0] = ISCDictItem("a", agentID.data);
+params.items[1] = ISCDictItem("N", nativeTokenID);
+```
+
+3. Now, you can use [`callView`](../../reference/magic-contract/ISCSandbox.md#callview) to call our contract. The first parameter is the core contract `hname`, which we can get with the helper utility [`hn`](../../reference/magic-contract/ISCUtil.md#hn), and the second parameter is the function we want to call. The last parameter is the dictionary with all function parameters.
+
+```solidity
+ISCDict memory result = ISC.sandbox.callView(
+    ISC.util.hn("accounts"),
+    ISC.util.hn("balanceNativeToken"),
+    params
+);
+```
+
+4. Next, you can either return or emit the result.
+
+```solidity
+emit NativeTokenBalance(bytesToUint(result.items[0].value));
+```
+
+:::info Return Dictionary
+
+Keep in mind that the call and callView functions will always return a dictionary. The values of this dictionary are always of type byte, so you need to take care of converting it yourself.
+
+:::
+
+### Full Example Code 
+
+```solidity
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.0;
+
+import "@iota/iscmagic/ISC.sol";
+
+contract NativeTokenBalance {
+    event NativeTokenBalance(uint balance);
+
+    function getNativeTokenBalance(bytes memory nativeTokenID) public {
+        ISCAgentID memory agentID = ISC.sandbox.getSenderAccount();
+
+        ISCDict memory params = ISCDict(new ISCDictItem[](2));
+        params.items[0] = ISCDictItem("a", agentID.data);
+        params.items[1] = ISCDictItem("N", nativeTokenID);
+
+        ISCDict memory result = ISC.sandbox.callView(
+            ISC.util.hn("accounts"),
+            ISC.util.hn("balanceNativeToken"),
+            params
+        );
+
+        emit NativeTokenBalance(bytesToUint(result.items[0].value));
+    }
+
+    function bytesToUint(bytes memory b) internal pure virtual returns (uint256) {
+        require(b.length <= 32, "Bytes length exceeds 32.");
+        return abi.decode(abi.encodePacked(new bytes(32 - b.length), b), (uint256));
+    }
+}
+```

docs/build/isc/v1.0.0-rc.6/docs/how-tos/core-contracts/introduction.md

@@ -51,6 +51,12 @@ If you need further info about magic contracts interfaces you can check out the
 
 ## Call a Function
 
+:::info Ease of use
+
+To make it easier for developers to use the core contracts, you should, in most cases, run the functions from the magic contract directly. For example, to get the native token balance, you could [call the `balanceNativeToken()`](./call-view.md) directly with `callView`, or use [`getl2balancenativetokens`](./basics/get-balance.md) of the magic contract, or (the suggested way) register your native token as [`ERC20`](../../reference/magic-contract/ERC20NativeTokens.md) and call the standard [`balanceof`](../../reference/magic-contract/ERC20NativeTokens.md#balanceof) function. What you use also depends on what you optimize for. For example, to save gas, it could be interesting for you to call core contracts from your favorite web3 library directly and compute other things off-chain.
+
+:::
+
 In the example below, `ISC.sandbox.getEntropy()` calls the
 [`getEntropy`](https://github.com/iotaledger/wasp/blob/develop/packages/vm/core/evm/iscmagic/ISCSandbox.sol#L20)
 method of the `ISCSandbox` interface, which, in turn,

docs/build/isc/v1.0.0-rc.6/sidebars.js

@@ -176,6 +176,11 @@ module.exports = {
               label: 'Get Randomness on L2',
               id: 'how-tos/core-contracts/get-randomness-on-l2',
             },
+            {
+              type: 'doc',
+              label: 'Call and Call View',
+              id: 'how-tos/core-contracts/call-view',
+            },
           ],
         },
       ],